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
@@ -108,11 +108,14 @@ same write at the moment it tries it, instead of letting it surface as a CI fail
108
108
  Revoke-on-change is enforced at merge: on **GitHub** in code (an approval whose commit ≠ the merged
109
109
  head is dropped — no setting needed); on **GitLab** it has no per-approval commit SHA, so enabling the
110
110
  platform's **"remove all approvals when commits are added to the source branch"** is **required** for
111
- the guarantee. Either way it is safe because CI never pushes the review branch — only the owner's own
112
- artifact pushes dismiss approvals. In verified mode `yad gate sync` is advisory (read-only) and is **not**
113
- a recovery path; if a merge-time run fails, the scheduled reconcile job re-advances it automatically, or
114
- a maintainer can force it with `yad gate ci --branch <review-branch> --pr <n> --merged` locally on the
115
- default branch. (local mode keeps `yad gate sync` as the local writer.)
111
+ the guarantee. It is a platform setting, so the person turns it on (E158); confirm it with
112
+ `glab api projects/:id/approvals` (`reset_approvals_on_push: true`). Either way it is safe because CI
113
+ never pushes the review branch — only the owner's own artifact pushes dismiss approvals. In verified
114
+ mode `yad gate sync` is advisory (read-only) and is **not** a recovery path; if a merge-time run fails,
115
+ the scheduled reconcile job re-advances it automatically, or a maintainer can force it with
116
+ `yad gate ci --branch <review-branch> --pr <n> --merged` locally on the default branch. That is the
117
+ person's to run, never an AI agent's: it pushes to the default branch (E158). (local mode keeps
118
+ `yad gate sync` as the local writer.)
116
119
 
117
120
  1. Run `yad check --fix` (the wiring is manifest-driven, like `yad-checks`): with a platform +
118
121
  enabled bridge in `.sdlc/product.json` it installs
@@ -132,7 +135,16 @@ default branch. (local mode keeps `yad gate sync` as the local writer.)
132
135
  from the template. See `references/bridge.md`.
133
136
  2. **GitLab only — two one-time steps** (see the fragment's header for the exact recipes):
134
137
  - add `include: - local: '.gitlab/ci/yad-gate-sync.yml'` to the root `.gitlab-ci.yml`, or write
135
- `templates/gitlab/gitlab-ci.include-root.yml` as the root when none exists;
138
+ `templates/gitlab/gitlab-ci.include-root.yml` as the root when none exists. This is a file in the
139
+ repo: an AI agent adds it on its own branch and opens a PR/MR, or asks before committing it to the
140
+ default branch (E158);
141
+ - the rest of this step (the schedule, the token, the CI/CD variables) is project settings, so it is
142
+ the person's (E158): an AI agent gives them the steps, never sets one itself, then confirms by
143
+ reading. `glab api projects/:id/pipeline_schedules` shows the schedule. Never read the token or
144
+ a variable through the API: GitLab's answer holds the secret value. Ask the person instead. A green
145
+ scheduled `yad-gate-sync` run proves the schedule and that the token can read the API; its right to
146
+ push shows only once a run advances a merged review MR, so until then check the token's scopes and
147
+ role with the person. `yad doctor` does not check these;
136
148
  - create the 15-minute pipeline **schedule** (variable `SDLC_GATE_SYNC=true`) and the masked
137
149
  `SDLC_GATE_TOKEN` project-access-token variable (`read_api` + `write_repository`). GitLab fires no
138
150
  pipeline on an approval alone, and a squash merge can drop the branch name, so the schedule is the
@@ -146,17 +158,32 @@ default branch. (local mode keeps `yad gate sync` as the local writer.)
146
158
  case set the variable to a real tag. The variable lives in project settings, so it survives
147
159
  every `yad` sync. Single value only — `tags: [$VAR]` is one tag equal to the whole variable,
148
160
  not a comma-split.
161
+ - **The Node line** (#364): the job runs `image: node:${YAD_NODE_VERSION}`, `22` by default; set a
162
+ `YAD_NODE_VERSION` CI/CD variable to change it without editing the managed fragment. Leave
163
+ **Protect variable** unticked on it and on `YAD_RUNNER_TAGS` unless only protected branches run
164
+ yad jobs — a protected variable never reaches an unprotected branch's pipeline. A
165
+ **shell-executor** runner ignores `image:`: the job then runs on the runner host, which needs
166
+ `bash`, `git`, `curl` and Node with `npx` on the runner user's `PATH`. The job also installs a
167
+ pinned `glab` package with `dpkg -i` (root) and puts `jq` (and `git-lfs` when the Product uses LFS)
168
+ in `/usr/local/bin`, all `linux_amd64` builds — so a shell runner must be an x86-64 Debian-family
169
+ host whose runner user may do that; otherwise use a docker executor for this job. `yad doctor`
170
+ warns on a fragment that still runs a fixed `node:<n>` image (`YAD-CI-002`); `yad update`
171
+ replaces it — or, if `yad check` lists the file as `modified` (edited by hand), move the change
172
+ into the CI/CD variables (the person sets them; an AI agent gives the steps, E158), then, when the
173
+ person asks, run `yad update --overwrite-local`, which keeps a `.yad-orig` copy of each file it
174
+ replaces.
149
175
  - **Git LFS needs nothing extra.** For a Product that uses Git LFS, the runner installs LFS git
150
- hooks that fail without `git-lfs`, and the job's `node:20` image has none — so the job downloads a
176
+ hooks that fail without `git-lfs`, and the job's node image has none — so the job downloads a
151
177
  pinned `git-lfs` itself before its checkout (#327; a Product without LFS skips it). A
152
178
  `before_script` added by hand to install `git-lfs` can be removed after `yad update`.
153
179
  3. Commit the workflow to the Product. GitHub needs nothing else — the ephemeral `github.token` reads the
154
180
  PR and pushes the merge advance to the default branch, and the workflow's reconcile **schedule**
155
181
  runs automatically (no setup) as the safety net that recovers a merge whose run failed transiently.
156
182
  If the default branch is protected, see the workflow header for the bypass / PAT options; until then
157
- the run fails visibly — recover by granting the push path, then re-run the workflow or run
158
- `yad gate ci --branch <review-branch> --pr <n> --merged` locally on the default branch (advisory
159
- `yad gate sync` cannot recover a bridge gate).
183
+ the run fails visibly. The person recovers it (E158: an AI agent gives the steps, then confirms with
184
+ `yad gate status <epic>` after `git pull --ff-only` on the default branch): grant the push path (a branch-protection or ruleset setting), then re-run
185
+ the workflow or run `yad gate ci --branch <review-branch> --pr <n> --merged` locally on the default
186
+ branch (advisory `yad gate sync` cannot recover a bridge gate).
160
187
 
161
188
  ## Hard rules
162
189
 
@@ -176,12 +203,17 @@ default branch. (local mode keeps `yad gate sync` as the local writer.)
176
203
  - **The CI tokens are the one documented bend of "no stored tokens".** GitHub uses the platform's own
177
204
  ephemeral `github.token` (nothing stored). GitLab requires a stored masked `SDLC_GATE_TOKEN`
178
205
  project access token because `CI_JOB_TOKEN` can neither read the approvals API nor push — say so
179
- when wiring, and scope it to `read_api` + `write_repository` only.
206
+ when wiring, and scope it to `read_api` + `write_repository` only. Making the token and setting it
207
+ are the person's (E158): give them these steps. Never read the variable through the API (GitLab's
208
+ answer holds the secret value); ask the person. A green scheduled `yad-gate-sync` run proves the token
209
+ can read the API; its right to push shows only once a run advances a merged review MR.
180
210
  - **Protect the Product default branch.** Require that `epics/**` artifacts change only through a review
181
211
  PR/MR (branch protection). This keeps revoke-on-change sound: it removes the only window where a
182
212
  delayed reconcile could advance on an out-of-band post-merge artifact change (see `references/bridge.md`,
183
213
  "Known limitation"). Safe to require: a new epic's `.sdlc/` seed rides its first review PR/MR, so
184
- nobody needs a direct push to the default branch to start an epic (#162).
214
+ nobody needs a direct push to the default branch to start an epic (#162). Branch protection is a
215
+ platform setting, so it is the person's (E158): give them the steps and confirm by reading
216
+ (`yad doctor`'s `protection` lines).
185
217
  - **Degrade gracefully.** No platform / disabled bridge / no CLI → the gate runs local with no error.
186
218
 
187
219
  ## Reference
@@ -123,8 +123,11 @@ repository access decides who may approve. A review with no login is not counted
123
123
  recorded one (numbers only grow within one repo), and syncs the recorded one instead. A newer review
124
124
  still moves it forward, so a re-review of a done step is still read (#156). Merges happen in any
125
125
  order, so on a step that is still open the older review is first read in a dry run: if it passes the
126
- gate, the pointer moves back to it once and the step advances (a held newer review cannot block an
127
- approved older one, and the manual recovery still works). A pointer from another platform never
126
+ gate, the pointer moves back to it once and the step advances (a held newer review that left the
127
+ artifact as the older one approved it cannot block it, and the manual recovery still works; one that
128
+ changed the artifact is content the older review never approved, so the gate holds until a fresh
129
+ review of the artifact as it stands — the approvals count only for the content at each review's head,
130
+ #366). A pointer from another platform never
128
131
  counts as newer, and before the pointer moves to a number other than the one it holds, `gate ci` asks the
129
132
  platform that the PR/MR is on the review branch — a mistyped `--pr` the platform places on another
130
133
  branch is refused, not recorded (one the platform cannot place is used as given, with a warning). A
@@ -327,7 +330,7 @@ nothing, so it is **not** a recovery path when CI fails. If a merge-time run fai
327
330
  (can't push, API hiccup), recovery is the scheduled **reconcile** job (automatic; it re-advances merged
328
331
  reviews not yet `done`). To force it immediately, a maintainer runs the same command CI runs, locally on
329
332
  the default branch: `yad gate ci --branch <review-branch> --pr <n> --merged` (this writes + pushes,
330
- unlike advisory `yad gate sync`). Local mode (no platform) keeps `yad gate sync` as the local writer.
333
+ unlike advisory `yad gate sync`; the person runs it, never an AI agent, E158). Local mode (no platform) keeps `yad gate sync` as the local writer.
331
334
  The file ledger is still the source of truth.
332
335
 
333
336
  Because CI records the PR-ledger pointer (`product-prs.json` + `hub-prs.json`) only at merge, a review the ledger has never seen still
@@ -348,7 +351,9 @@ to reject.
348
351
 
349
352
  **In verified mode `gate sync` stays advisory even with `--pr`** — it prints the predicate and writes
350
353
  nothing, because CI owns the ledger. The recovery that actually writes is the command CI itself runs,
351
- on the default branch: `yad gate ci --branch <review-branch> --pr <n> --merged`.
354
+ on the default branch: `yad gate ci --branch <review-branch> --pr <n> --merged`, which the person runs
355
+ (an AI agent gives the command and confirms with `yad gate status <epic>` after `git pull --ff-only` on
356
+ the default branch, E158).
352
357
 
353
358
  **Serialization.** Both wired jobs push the ledger to the default branch, and on GitLab the scheduled
354
359
  sweep's recent-MR window overlaps whatever the merge-push pipeline is handling — so they are pinned to
@@ -367,7 +372,8 @@ rather than failing inside `gh`/`glab`; an origin that cannot be reached at all
367
372
  ### Manual end-to-end verification (GitHub)
368
373
 
369
374
  1. On a scratch Product: `yad setup` (platform github; a second account with write access to review) → `yad check --fix`
370
- installs `.github/workflows/yad-gate-sync.yml`; commit + push it.
375
+ installs `.github/workflows/yad-gate-sync.yml`; commit + push it (an AI agent asks first: it is the
376
+ default branch, E158).
371
377
  2. Author an epic → `yad gate open EP-x epic.md` → the review PR opens. CI writes nothing yet — review
372
378
  state lives on the platform.
373
379
  3. Second account **approves** / **requests changes** → no CI run touches the branch; the PR's native
@@ -87,7 +87,7 @@ jobs:
87
87
  fetch-depth: 0
88
88
  - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
89
89
  with:
90
- node-version: "20"
90
+ node-version: "22"
91
91
  - name: Resolve the yadflow pin
92
92
  run: |
93
93
  # >>> yad-pin
@@ -170,7 +170,7 @@ jobs:
170
170
  fetch-depth: 0
171
171
  - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
172
172
  with:
173
- node-version: "20"
173
+ node-version: "22"
174
174
  - name: Resolve the yadflow pin
175
175
  run: |
176
176
  # >>> yad-pin
@@ -65,7 +65,12 @@ yad-gate-sync:
65
65
  # project Settings → CI/CD → Variables, so it survives every `yad` sync. When unset, current
66
66
  # GitLab (>=15) runs the job untagged; older versions may strand it — set a real tag if so.
67
67
  tags: [$YAD_RUNNER_TAGS]
68
- image: node:20
68
+ image: node:${YAD_NODE_VERSION}
69
+ variables:
70
+ # A project/group CI/CD variable overrides this YAML value, so the Node line can be changed in project
71
+ # settings without editing the managed fragment (a current 22 or 24 line). A shell-executor runner
72
+ # ignores `image:` — Node must then be on the runner host's PATH, and this value has no effect.
73
+ YAD_NODE_VERSION: "22"
69
74
  rules:
70
75
  # Merge path: branch pipeline on the default branch whose merge commit names a review branch.
71
76
  # Squash/fast-forward merges may omit the branch name — those advance on the next scheduled sweep.
@@ -73,17 +78,17 @@ yad-gate-sync:
73
78
  # Scheduled sweep: the only path that picks up bare approvals (advances merged reviews it finds).
74
79
  - if: $CI_PIPELINE_SOURCE == "schedule" && $SDLC_GATE_SYNC == "true"
75
80
  script:
76
- # Pinned glab binary (node:20 has no glab). Alternative: image registry.gitlab.com/gitlab-org/cli.
81
+ # Pinned glab binary (the node image has no glab). Alternative: image registry.gitlab.com/gitlab-org/cli.
77
82
  - GLAB_VERSION=1.55.0
78
83
  - curl -fsSL "https://gitlab.com/gitlab-org/cli/-/releases/v${GLAB_VERSION}/downloads/glab_${GLAB_VERSION}_linux_amd64.deb" -o /tmp/glab.deb && dpkg -i /tmp/glab.deb
79
- # Pinned jq binary (node:20 has none, and `glab api` has NO built-in --jq like `gh api` does —
84
+ # Pinned jq binary (the node image has none, and `glab api` has NO built-in --jq like `gh api` does —
80
85
  # it errors "unknown flag: --jq"). We fetch raw JSON from glab and filter it through real jq;
81
86
  # jq streams glab's concatenated per-page --paginate arrays natively.
82
87
  - JQ_VERSION=1.7.1
83
88
  - curl -fsSL "https://github.com/jqlang/jq/releases/download/jq-${JQ_VERSION}/jq-linux-amd64" -o /usr/local/bin/jq && chmod +x /usr/local/bin/jq
84
89
  # Pinned git-lfs, ONLY for a Product that uses Git LFS (issue #327). The runner clones an LFS repo
85
90
  # with its own git-lfs and installs LFS git hooks (post-checkout, pre-push, …) that exit with an
86
- # error when git-lfs is missing — and node:20 has none. So the `git checkout` below failed, and so
91
+ # error when git-lfs is missing — and the node image has none. So the `git checkout` below failed, and so
87
92
  # would the push of the advance. A Product without LFS skips the download. Only the clone's own
88
93
  # signs count (its hooks, its .git/config, its .gitattributes) — never a global git setting.
89
94
  # The download is checked against the release's published SHA-256 (sha256sums.asc) before it is
@@ -46,10 +46,16 @@ Run `yad reconcile check` (optionally `--thread EP-<genesis>`). For each thread
46
46
  - a **merged task with no ship record** — a `Task:` trailer, a merge commit naming a task branch, a full
47
47
  task ID in a commit subject (not a revert), or a merged task branch. For a story that has no ship in
48
48
  that repo it offers `yad checkpoint --retro-ship …` once, for a story that predates ledger tracking
49
- (its status must be `in-build` or `shipped` first); otherwise record the ship as `yad-engineer-review`
50
- does. A retroactive ship covers only the tasks merged up to it (by its merge commit or date);
49
+ (its status must be `in-build` or `shipped` first); otherwise record the ship with
50
+ `yad build ship <story> --task <T> --repo <r> --pr <n>`. **`yad build sync [<epic>]` (#365) records them all
51
+ at once**: each through `yad build ship` — from the PR/MR that merged it, or from its merge commit where the
52
+ platform confirms no PR/MR did — then `yad build done` for each story now fully shipped; what it cannot
53
+ record (no platform to read, a refusal, a story with no Build lane there — it may predate tracking) it lists
54
+ with the command to run. `--dry-run` only says what it
55
+ would run. A retroactive ship covers only the tasks merged up to it (by its merge commit or date);
51
56
  - a story whose every repo holds merged work or a ship, but whose `status:` is not `shipped` — a hint,
52
- not counted: if no task is left, set `status: shipped`;
57
+ not counted: if no task is left, run `yad build done <story>` — when it refuses (no lane yet, a repo
58
+ not cloned), its message names what to run first;
53
59
  - a **possible match** to check by hand, for a story not yet shipped or recorded in that repo: a full
54
60
  story ID in a commit subject with no task, or a short scope tag such as `feat(s06):`. Never counted. A
55
61
  story ID only in a commit body is not evidence.
@@ -39,6 +39,21 @@ check list. Free-text fields (the summary, the error message) are scrubbed of pa
39
39
  URL. Otherwise, fall back to a **prefilled `issues/new` URL** (printed and, on a TTY, opened in the
40
40
  browser) so the user can complete it manually.
41
41
 
42
+ ## From an AI agent (E158)
43
+ An agent that finds a bug in yadflow, or a clear way yadflow could do better, while it works (not a
44
+ problem in the person's own project):
45
+ 1. `yad report -m "<one line>" --kind bug|enhancement --json` — a preview; it never posts. Write the line
46
+ in general words: never a project name, code, a path, a branch, an id or a person.
47
+ 2. Show the person the `title` and `body` exactly, and any `related` issues; if one matches, suggest adding
48
+ to it instead.
49
+ 3. Ask every time — it goes to a public repo.
50
+ 4. On a yes: `yad report -m "<the same line>" --kind <the same kind> --post --confirm <confirm>`, with the
51
+ `confirm` value from step 1. yad posts only when the text is exactly what the person saw; anything else
52
+ posts nothing, and the agent previews and asks again. With no `gh` login it prints the prefilled link.
53
+
54
+ `--kind enhancement` labels it `enhancement`, titles it `[report] Enhancement: …`, and leaves out the error
55
+ block.
56
+
42
57
  ## Hard rules
43
58
  - Reuse the `yad report` command — do not craft issues by hand or shell out to `gh` directly.
44
59
  - Reporting is best-effort: it must never crash the CLI or mask the original failure.
@@ -63,18 +63,20 @@ Inputs: `epic` + `artifact` (Shape) **or** `repo` + `pr` (Build); and the `actio
63
63
  comment so it blocks.
64
64
  4. **Chat.** Answer from the material with cited lines. Append the Q&A log as a `<!-- yad:noblock -->`
65
65
  comment so it persists in history without blocking. Turn genuine concerns into unflagged comments.
66
- 5. **Approve.** When the reviewer is satisfied, submit an Approve whose body carries
66
+ 5. **Approve.** When the reviewer is satisfied, they submit an Approve — never you, even when your login could
67
+ (E158: approving a PR/MR is the person's). Give them the exact command, whose body carries
67
68
  `<!-- yad:engagement verified -->` (so the gate records `engagement: verified`). GitHub:
68
69
  `gh pr review <n> --approve --body "<note>\n\n<!-- yad:engagement verified -->"`. GitLab: approve,
69
70
  then post the marker as a note (`glab mr approve <n>` + `glab mr note <n> -m "…<!-- yad:engagement verified -->"`).
71
+ In Claude Code they type it with `!` in front. Then confirm by reading (`gh pr view <n>`, `glab mr view <n>`).
70
72
  6. **Nudge.** A bare approve (engagement `none`) still counts under the soft default; `yad gate sync`
71
73
  posts the friendly @-mention automatically. You may also post it directly with the
72
74
  `<!-- yad:noblock -->` marker.
73
75
 
74
76
  ## Hard rules
75
77
 
76
- - **Never write a ledger file.** Post comments / the trailer / the approval to the PLATFORM (the
77
- reviewer's own `gh`/`glab`). CI writes `approvals.json`/`comments.json`; the `ledger-guard` check
78
+ - **Never write a ledger file.** Post comments and the trailer to the PLATFORM; the reviewer posts the
79
+ approval with their own `gh`/`glab`. CI writes `approvals.json`/`comments.json`; the `ledger-guard` check
78
80
  rejects a human ledger edit on a review PR. The markers ride in platform data only.
79
81
  - **Trailer/cards/chat are grounded ONLY in real material.** If the material does not answer a
80
82
  question, say so and record the gap — do not fabricate.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: yad-review-gate
3
- description: 'The reusable team review + approve gate for the SDLC. Shares an authored artifact for review, records reviewer comments and approvals as files, enforces the approver count (1 distinct approver; contract/auth/payments raise the full count, advisory), and advances the epic state ONLY when approval is recorded. Use when the user says "review the analysis/epic/architecture/UI/stories/test-cases", "comment", "approve", or "advance the gate".'
3
+ description: 'The reusable team review + approve gate for the SDLC. Shares an authored artifact for review, syncs the reviewers'' comments and approvals into files, enforces the approver count (1 distinct approver; contract/auth/payments raise the full count, advisory), and the step advances ONLY when approval is recorded. Commenting, approving, advancing and reopening are the person''s acts: an AI agent gives them the exact command and confirms by reading, never runs it. Use when the user says "review the analysis/epic/architecture/UI/stories/test-cases", "comment", "approve", or "advance the gate".'
4
4
  ---
5
5
 
6
6
  # SDLC — Team Review Gate (build plan §3 piece 2, §4, §5)
@@ -30,6 +30,10 @@ trigger is a parameter, not a hardcoded human.
30
30
  - `artifact`: the file under the epic being reviewed (e.g. `epic.md`).
31
31
  - `action`: one of `open` | `comment` | `approve` | `sync` | `advance` (default: `open`). With no platform,
32
32
  `comment` / `approve` / `advance` are the `yad gate comment|approve|advance` commands (E112).
33
+ **These, and `yad gate reopen`, are the person's to run, never yours (E158).** Give the person the exact
34
+ command (in Claude Code they type it with `!` in front, so its output lands in the chat), wait, then
35
+ confirm by reading — `yad gate status <epic>` — before you go on. Never go on from "done" alone. The agent
36
+ guard hook refuses them if you try.
33
37
  - For `comment` / `approve`: the reviewer's platform login (or the name they give, when there is no
34
38
  platform). No role and no domain. Ask if not provided.
35
39
  - `sync` needs no reviewer input — it reads the platform PR/MR review state (via `yad-product-bridge`).
@@ -140,7 +144,7 @@ CI records the gate at merge.) Opening the PR records no approvals and never adv
140
144
  - <comment>
141
145
  ```
142
146
 
143
- Then record the round with the engine — **never append to `.sdlc/comments.json` by hand**:
147
+ Then the reviewer records the round with the engine — give them the command, and never append to `.sdlc/comments.json` by hand:
144
148
  ```bash
145
149
  yad gate comment <epic> <artifact> --by <name> --count <comments this round> # the round in progress
146
150
  yad gate comment <epic> <artifact> --by <name> --count <n> --new-round # after the owner addressed the last round
@@ -158,14 +162,14 @@ Then help the **owner address the comments** using the agent lens listed for thi
158
162
  stories → `pm`, with `architect` for technical detail; test-cases → `test architect`). Update the authored artifact in place.
159
163
  Repeat comment→address rounds until reviewers are satisfied. **Commenting never advances the gate.**
160
164
 
161
- **`approve`** — Record an approval with the engine — **never append to `.sdlc/approvals.json` by hand**:
165
+ **`approve`** — The reviewer records their approval with the engine — give them the command, and never append to `.sdlc/approvals.json` by hand:
162
166
  ```bash
163
167
  yad gate approve <epic> <artifact> --by <name> [--engagement verified|none]
164
168
  ```
165
169
  One record per person (a second approval by the same name replaces the first). It records no `role` or
166
170
  `domain`. The approver must not be the artifact's author: the command warns when `--by` is the epic's
167
- `owner:` or the artifact's last git author, and records it anyway (it cannot tell who is typing), so do
168
- not run it for the author. The record carries the artifact's fingerprint (`artifactHash`), so **an edit to
171
+ `owner:` or the artifact's last git author, and records it anyway (it cannot tell who is typing), so never
172
+ hand it to the author. The record carries the artifact's fingerprint (`artifactHash`), so **an edit to
169
173
  the artifact revokes it**, exactly as a platform approval is revoked — the reviewer approves again once they
170
174
  have seen the new content. An older hand-written record with no fingerprint still counts until it is
171
175
  replaced. This is the **no-platform** path (E112): with a platform the approvals are the PR/MR's, and the
@@ -228,8 +232,8 @@ writes neither (issue #362). Always **re-evaluate Step 3**. **Never hand-write e
228
232
  gate sync`), `sync` advances the step when Step 3 passes on a **merged**, fully-resolved, approved PR
229
233
  (the merge is the human act); otherwise it records state and holds the step `in_review`.
230
234
 
231
- **`advance`** — Run the gate predicate (Step 3) and advance only if it passes. With no platform that is
232
- `yad gate advance <epic> <artifact>`; with a platform it is the merge (`yad gate sync` / `yad gate ci`).
235
+ **`advance`** — Check the gate predicate (Step 3); only when it passes, the person advances. With no platform
236
+ that is `yad gate advance <epic> <artifact>`, which they run; with a platform it is the merge (`yad gate sync` / `yad gate ci`).
233
237
 
234
238
  ### Step 3 — Gate predicate (the only path that advances)
235
239
  The step may advance **iff ALL hold**:
@@ -248,7 +252,7 @@ The step may advance **iff ALL hold**:
248
252
  `../yad-architecture/references/contract-format.md`): if it no longer matches
249
253
  `.sdlc/contract-lock.json`, the surface changed → approvals stale → return to `comment` and re-lock.
250
254
 
251
- If the predicate **passes**, advance with the engine — **never edit `state.json` by hand**:
255
+ If the predicate **passes**, hand the person the command that advances it — **never edit `state.json` by hand**:
252
256
 
253
257
  ```bash
254
258
  yad gate advance <epic> <artifact> # a Product with no platform (E112)
@@ -336,6 +340,10 @@ write path.
336
340
  whether approvals arrive manually or via `sync`. With no Product platform / no CLI, the gate runs local
337
341
  with no error: `yad gate approve`, `yad gate comment` and `yad gate advance` record the review in the
338
342
  engine (E112).
343
+ - **A passed gate is taken back only by `yad gate reopen`** (#322), and only before Build starts:
344
+ the person runs `yad gate reopen <epic> <step> --reason "<why>"`, which walks the chain back to the step and revokes the
345
+ later reviews' approvals, so each gate runs again. Never edit `state.json` or `approvals.json` by hand
346
+ to do it.
339
347
 
340
348
  ## Reference
341
349
  - Gating details and worked example: `references/gating.md`.
@@ -203,7 +203,32 @@ content. This prevents "approve, then quietly change it" (build plan §5 spirit)
203
203
  The engine checks this by content, not by date. A bridge approval records `artifactHash`, the
204
204
  fingerprint of what was approved. When the artifact's fingerprint no longer matches, the approval is
205
205
  counted as revoked: it stays on disk, it no longer counts, and the gate reports `N approval(s) revoked —
206
- artifact changed; re-approve`. An approval recorded with no `artifactHash` is never treated as stale.
206
+ artifact changed; re-approve`.
207
+
208
+ The fingerprint is taken of the content **at the review PR/MR's head**, the commit its reviewers
209
+ approved, never of the default branch when the gate happens to read it (#366). Several reviews can
210
+ cover one artifact (per-story `review/<epic>/stories-S0N` branches, or a re-review on a fresh MR), and
211
+ another one merged in between, without approvals, would otherwise pass on these approvals. So a
212
+ merged review whose head differs from the default branch passes nothing, and the gate says so and
213
+ names the fix: review the artifact as it stands on a fresh PR/MR — fetch with `git fetch --prune origin`, reset the branch `review/<epic>/<artifact>` to the default branch (`git switch -C`: the merged review's branch is usually still there), add a commit (an empty one is enough: `git commit --allow-empty`), push it with `--force-with-lease`, then run `yad gate open <epic> <artifact>`. The force push is the person's (E158: an agent never force-pushes): an agent gives them the steps, and runs `yad gate open` once they say it is pushed and `git ls-remote origin review/<epic>/<artifact>` shows it. A default branch
214
+ with nothing to fingerprint (every story deleted, a contract with no END marker) passes no approval of
215
+ real content either, and solo mode, which counts no approvals, says nothing. A step already done is
216
+ only re-synced: no hold is printed, and its approvals keep the fingerprint they were recorded with.
217
+ When a later merge changes a done step's artifact and none of its approvals covers it any more, the
218
+ gate says so loudly — `<step> is done, but <artifact> changed after it was approved` — with the same
219
+ fresh-review steps, and never reopens or blocks the step (#418). `yad doctor`, `yad status` (owed) and
220
+ `yad next` say it too, until a fresh review's approvals cover the artifact as it stands (`status` and
221
+ `next` not in solo mode, where no approval is counted). Each file at the head is
222
+ read through git's checkout filters, so line-ending conversion gives the bytes the disk holds.
223
+ A squash-merged head is fetched from the platform's own ref (`refs/pull/<n>/head`,
224
+ `refs/merge-requests/<n>/head`); a head that cannot be read records nothing and turns the CI run red on a step not yet done (on a step already done it is said and skipped, and a later sweep tries again).
225
+ Two limits: GitLab approvals carry no commit, so an approval given before later pushes to the same MR
226
+ is bound to the head when it was first read, and stays bound there — on a local
227
+ ledger it then does not count at merge when the artifact changed after it, and in CI (which reads at
228
+ merge) it counts against the merged head; the project's "reset approvals on push"
229
+ setting covers both; and a
230
+ branch rebased onto the default branch carries the content merged there, which its reviewers then
231
+ approved with it. An approval recorded with no `artifactHash` is never treated as stale.
207
232
  A hand-written approval (the `approve` action, on a Product with no platform) carries no fingerprint and
208
233
  no platform evidence, so an edit to the artifact does **not** revoke it: after a real change, remove the
209
234
  old approval and record it again once the reviewer has seen the new content.
@@ -30,15 +30,17 @@ beside it as advice and never refuses on it. The kill switch (`yad kill`) holds
30
30
  - Automation config is `.sdlc/config.yaml` → `automation:` (`back_steps`, `default`). The kill
31
31
  switch and the Shape dials live in `.sdlc/automation.json`, and are read and written **only through the
32
32
  engine** — `yad dial … --json`, `yad kill`, `yad unkill`. Never read or edit either file for a dial.
33
- - Per-story Build state: `epics/<epic>/.sdlc/build-state/<story-id>.json` (per repo).
34
- - Trust ledger: **shard-then-fold** — each run is its own shard file
33
+ - Per-story Build state: `epics/<epic>/.sdlc/build-state/<story-id>.json` (per repo), written by
34
+ `yad build start` and `yad build step` — never by hand.
35
+ - Trust ledger: **shard-then-fold**, written by `yad build trust` — each run is its own shard file
35
36
  `epics/<epic>/.sdlc/trust-log/<story>-<repo>-<step>-<uid>.json` (a fresh `uid` per run, so concurrent
36
37
  writers never conflict); readers UNION the folded `trust-log.json` with every loose shard, and
37
38
  `yad tidy up` folds finished shards back into `trust-log.json`. Schemas:
38
39
  `../yad-epic/references/state-schema.md`.
39
40
  - These machine-written Build files (`build-state/<story>.json`, the `trust-log/` shards) are
40
41
  committed by **`yad checkpoint`** — the Build analogue of the Shape `yad gate` sync; the loop
41
- calls it each iteration so the state is durable and shared without a human commit. (`yad checkpoint`
42
+ calls it each iteration so the state is durable and shared without a human commit — its `--push`, which
43
+ lands on the default branch, only after the person says yes (E158). (`yad checkpoint`
42
44
  stages the shard dirs; `yad tidy up` later folds finished shards — loose objects + `git gc`.)
43
45
  - The orchestrator **calls the existing step skills unchanged** — `yad-spec` (A), `yad-implement`
44
46
  (B), `yad-checks` (C). It owns only the *advance decision*, never what a step does.
@@ -50,8 +52,11 @@ beside it as advice and never refuses on it. The kill switch (`yad kill`) holds
50
52
 
51
53
  - `epic` / `story` / `repo` — the story and code repo to drive (ask if not provided).
52
54
  - `action` — `run` (default) | `set-dial` | `kill` | `unkill`.
53
- - For `run`: optional `from` (the step id to start at; default the repo's `currentStep` in
54
- build-state) and `task` (the atomic task id for the `implement`/`checks` legs).
55
+ - For `run`: `task` (the atomic task id for the `implement`/`checks` legs — when not given, the task
56
+ `yad-implement` works on; every trust run and close on those legs names it with `--task`) and `from`. The lane
57
+ is walked in order, so `from` may only name the lane's current step — or, with `task`, `implement`
58
+ once the lane is at `engineer-review`: that reopens `implement` and `checks` for the next task
59
+ (`yad build step <story> --repo <repo> implement in_progress --task <task>`).
55
60
  - For `set-dial`: `step` (a `back_steps` id), `to` — `human` | `auto` (the older `human_approve` |
56
61
  `machine_advance` mean the same two things).
57
62
  - For `kill`: `reason` (required). For `unkill`: an optional `reason`.
@@ -59,14 +64,14 @@ beside it as advice and never refuses on it. The kill switch (`yad kill`) holds
59
64
  ## On Activation
60
65
 
61
66
  ### Step 0 — Load state
62
- Read `config.yaml` `automation` (for `back_steps`), the story's `build-state/<story>.json` (create it from the
63
- `back_steps` defaults if absent — all `advance: human` (`automation: human_approve`), `engineer-review` `locked:true`, and
64
- **write it to disk before the loop starts**, because `yad next` reads that file to know this lane
65
- exists), and `trust-log.json` (treat missing as `[]`). Resolve the code repo.
66
-
67
- If the file exists but has **no entry for this `repo`**, add that repo's entry from the same `back_steps`
68
- defaults — the file may already hold another repo, or a skipped lane — and never remove an entry you did
69
- not add. If this repo's entry is **`status: skipped`** (E39: the whole lane was set aside with
67
+ Read `config.yaml` `automation` (for `back_steps`), the story's `build-state/<story>.json`, and
68
+ `trust-log.json` (treat missing as `[]`). Resolve the code repo. If the story has **no lane for this
69
+ `repo`** (no file, or a file without that repo's entry), run `yad build start <story> --repo <repo>` **before
70
+ the loop starts**: it writes the lane from the `back_steps` defaults (all `advance: human`,
71
+ `engineer-review` locked) and never touches another repo's entry, and `yad next` reads that file to know
72
+ the lane exists. Never write `build-state/` or `trust-log/` by hand — the `yad build` commands write them
73
+ in the shape every reader expects (#346).
74
+ If this repo's entry is **`status: skipped`** (E39: the whole lane was set aside with
70
75
  `yad skip <epic> <story> --repo <repo>`, because the story needs no change in this repo), **do not drive
71
76
  it**: stop, report the recorded `record.reason`, and point at `yad unskip <epic> <story> --repo <repo>` if
72
77
  the lane is owed after all. **Never write a Build step as `skipped` or `deferred`**: a lane is skipped
@@ -91,43 +96,63 @@ Walk the steps for `repo` starting at `from`/`currentStep`. For each step:
91
96
  winning. Unbound, the engine answers `spec`→`yad-spec`, `tasks`→ the tasks leg of `yad-spec`,
92
97
  `implement`→`yad-implement`, `checks`→`yad-checks`, which is what this step used to say. Pass
93
98
  `action: run` to `yad-checks`. Capture the result.
94
- 2. **Derive trust signals & write a trust-log shard** — write the entry to its own file
95
- `trust-log/<story>-<repo>-<step>-<uid>.json` (a fresh `uid` per run; never append to a shared file),
96
- with `ranBy: machine` if this advance was automated, else `human` — see `references/run-loop.md` for
97
- the derivation. Do this for *every* step run, pass or fail; the log is the evidence base.
99
+ 2. **Derive trust signals & record the run** — `yad build trust <story> --repo <repo> <step> --verdict <v>
100
+ --signal <name>=<value> … --ran-by <machine|human> --json` writes the entry to its own shard with a fresh
101
+ `uid` and prints it (`ranBy: machine` if this advance was automated, else `human`) — see
102
+ `references/run-loop.md` for the derivation. Do this for *every* step run, pass or fail; the log is the
103
+ evidence base. Keep the `uid`: the closing record names it. **One exception (#357):** when the
104
+ step's skill stopped to ask its human-only questions (its first batch or a later one), the step's
105
+ output is not finished, and a draft is not output to judge: record no trust entry. Run
106
+ `yad build step <story> --repo <repo> <step> blocked [--task <task>] --reason "waiting on human
107
+ decisions: <the questions, short>"`, ask the person before `yad checkpoint --push` (a push to the default
108
+ branch is asked about every time, E158), and stop — skip steps 3 and 4.
109
+ **Not when the skill also hit its contract STOP** (a contract-change item in its batch): no answer
110
+ lifts that, so it is the step-4 contract-touch halt, with its trust entry, as before.
98
111
  3. **Ask the engine for the effective dial:** `yad dial <epic> <story> --repo <repo> <step> --json`, and use
99
112
  its `advance`. It is `human` whenever the step is a gate (`why: gate` — a read never refuses one), the kill switch
100
113
  is on, or `.sdlc/automation.json` cannot be read (`automationError` says so) — so never work the dial out from the files yourself.
101
114
  4. **Decide:**
102
115
  - **HALT** if the step failed — any check FAIL, a scope overrun (`yad-implement` stopped on the
103
- file-boundary rule), a contract-surface touch, or any ambiguity. Set the step `status: blocked`
104
- **with a `record`** — `{ "reason": "<the halt cause>", "by": "<login or null>", "date":
105
- "<YYYY-MM-DD>" }` — write the `rejected` trust entry, **stop the loop**, and report what a human
106
- must resolve. The record is not decoration: since shape 7 a `blocked` step with nothing recorded
116
+ file-boundary rule), a contract-surface touch, or any ambiguity other than the human-only
117
+ questions step 2 already halted on. Run
118
+ `yad build step <story> --repo <repo> <step> blocked --reason "<the halt cause>"` (it writes the
119
+ step's `record`) — the trust entry step 2 recorded for this run is the `rejected` one, so record
120
+ no second entry — **stop the loop**, and report what a human must resolve. The record is not decoration: since shape 7 a `blocked` step with nothing recorded
107
121
  on it reads as `todo` ("not started"), so a halt written without one is indistinguishable from a
108
122
  lane nobody has begun. `yad doctor` reports the difference as `step:no-record`.
109
- - else if effective dial is **`advance: auto`** → set the step `done` **with a `closed`** —
110
- `{ "by": "<login or null>", "date": "<YYYY-MM-DD>", "via": "auto", "run": "<the trust-log uid>" }` —
111
- advance `currentStep` to the next step, and **continue the loop** (this is the Step B auto-advance
112
- for `checks`).
113
- - else (**`advance: human`**) → set the step `done`/`in_review`, and give a `done` step a `closed` —
114
- `{ "by": "<login or null>", "date": "<YYYY-MM-DD>", "via": "human", "run": "<the trust-log uid>" }` —
115
- then **stop** and report "waiting for a human at `<next-step>`".
123
+ - else if effective dial is **`advance: auto`** → `yad build step <story> --repo <repo> <step> done
124
+ --via auto --run <uid>` (it writes the `closed` record and moves `currentStep` on), and **continue the
125
+ loop** (this is the Step B auto-advance for `checks`).
126
+ - else (**`advance: human`**) → `yad build step <story> --repo <repo> <step> done --run <uid>`, then
127
+ **stop** and report "waiting for a human at `<next-step>`".
128
+ - On the `implement`/`checks` legs, pass `--task <task>` to `yad build trust` and `yad build step`, so
129
+ each task's run and close are kept apart (the engineer review finalizes the right one).
116
130
  - `closed` is the step's **closing record** (E18): how the lane moved past it, and which run did it.
117
131
  Never write one over a `closed` already on the step. See `references/run-loop.md`.
118
- 5. **Always stop at `engineer-review`** (it is `locked`): hand off to `yad-engineer-review` for the human merge
132
+ 5. **Opening the task's PR/MR (#356).** Once `checks` has closed `done` for a task — by either dial, before
133
+ you stop — ask
134
+ `yad dial open-pr --json` and use its `advance`. **`auto`** — the project's standing approval: from the
135
+ task branch, run `yad open-pr --via auto` **without asking**. It refuses (and pushes nothing) unless the
136
+ dial is auto, the `checks` step is closed now, and each task the branch's commits carry (one, or a
137
+ group of small tasks of the story — #350) has its newest close naming it (so close it with `--task <T>`)
138
+ with a run that passed (`checks=pass`) and was not rejected; it records the opened PR/MR on the lane (`opened`). If it refuses, stop and report why.
139
+ **`human`** — stop and ask the person to approve opening it, then run `yad open-pr`. The merge is
140
+ always a person's, whatever the dial.
141
+ 6. **Always stop at `engineer-review`** (it is `locked`): hand off to `yad-engineer-review` for the human merge
119
142
  gate, which finalizes the trust verdict (confirm/override the provisional one).
120
143
 
121
144
  **Commit the machine-written state.** After each iteration's writes (the trust-log shard in 2 and the
122
- build-state change in 4), run `yad checkpoint --push` from `{project-root}`. It commits *only* the
145
+ build-state change in 4), ask the person, then run `yad checkpoint --push` from `{project-root}` (a push to
146
+ the default branch is asked about every time, E158). It commits *only* the
123
147
  `trust-log/` shards + `build-state/<story>.json` (never a Shape gate file) as one `chore(product): …`
124
148
  audit-trail commit, and only ever on the default branch. It is a safe no-op when nothing changed, so
125
- call it every iteration — teammates don't review these machine writes, but CI and the `yad-status` skill on
149
+ offer it every iteration — teammates don't review these machine writes, but CI and the `yad-status` skill on
126
150
  other machines must see current trust evidence. Never run it off the default branch (it will refuse):
127
151
  an unpushed or branch-stranded trust log leaves the run record `yad dial` shows out of date.
128
152
 
129
153
  ### `action: set-dial` — set (or revert) a step's advance dial
130
- Run `yad dial <epic> <story> --repo <repo> <step> --to <human|auto>` (map `human_approve` → `human` and
154
+ Only when the person asked for this exact change (E158): run
155
+ `yad dial <epic> <story> --repo <repo> <step> --to <human|auto>` (map `human_approve` → `human` and
131
156
  `machine_advance` → `auto` first). The engine writes both dial names on the lane step, refuses a gate and
132
157
  a lane step `yad-run` has not written yet, and prints the step's run record in that repo **as advice**.
133
158
  Relay its output. There is **no threshold** (E34): the team decides, and "it seems fine" is theirs to
@@ -137,7 +162,7 @@ For a Shape author step the team wants on auto, point at `yad dial <step> --to a
137
162
  recorded only: this loop never drives a Shape step.
138
163
 
139
164
  ### `action: kill` / `action: unkill` — the kill switch
140
- Run `yad kill --reason "<why>"` or `yad unkill [--reason "<why>"]`. The engine records who, when and why
165
+ Only when the person asked for it (E158): run `yad kill --reason "<why>"` or `yad unkill [--reason "<why>"]`. The engine records who, when and why
141
166
  in `.sdlc/automation.json`; while the switch is on, **every** step's effective dial is `human`. Tell the
142
167
  user to commit that file so every machine and CI sees it. Never set a `kill_switch` in `config.yaml`:
143
168
  nothing reads it, and `yad doctor` fails on one left `true`.
@@ -154,6 +179,9 @@ nothing reads it, and `yad doctor` fails on one left `true`.
154
179
  and the kill switch holds every step at human.
155
180
  - **The orchestrator never changes what a step does** — it calls the existing skills and owns only the
156
181
  advance decision and the trust record.
182
+ - **One epic per folder when agents run in parallel (#115).** Each orchestrator runs in its epic's own
183
+ worktrees (`yad worktree add <epic> --all`), never in a checkout another agent is using; `yad build`
184
+ and `yad checkpoint` run from there reach that epic's Product worktree.
157
185
 
158
186
  ## Reference
159
187
  - The loop and the trust-verdict derivation: `references/run-loop.md`.