yadflow 4.6.0 → 4.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +170 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +167 -15
  5. package/cli/artifact-status.mjs +88 -20
  6. package/cli/build.mjs +1372 -0
  7. package/cli/checkpoint.mjs +2 -2
  8. package/cli/commit.mjs +1 -0
  9. package/cli/dial.mjs +21 -1
  10. package/cli/docs.mjs +6 -1
  11. package/cli/doctor.mjs +133 -26
  12. package/cli/epic-state.mjs +357 -9
  13. package/cli/errors.mjs +2 -0
  14. package/cli/find-product.mjs +36 -2
  15. package/cli/fold.mjs +9 -5
  16. package/cli/gate-local.mjs +9 -1
  17. package/cli/gate.mjs +364 -22
  18. package/cli/history.mjs +22 -2
  19. package/cli/hook.mjs +3 -1
  20. package/cli/index-command.mjs +2 -2
  21. package/cli/ledger.mjs +60 -0
  22. package/cli/next.mjs +34 -11
  23. package/cli/openpr.mjs +81 -5
  24. package/cli/platform.mjs +21 -0
  25. package/cli/pr-list.mjs +5 -3
  26. package/cli/product-index.mjs +6 -3
  27. package/cli/product-token.mjs +186 -0
  28. package/cli/productcommit.mjs +33 -0
  29. package/cli/recommend.mjs +3 -1
  30. package/cli/repo-publish.mjs +2 -2
  31. package/cli/run-checks.mjs +586 -0
  32. package/cli/ship-drift.mjs +49 -18
  33. package/cli/standup.mjs +1 -1
  34. package/cli/status.mjs +282 -0
  35. package/cli/test-build.mjs +1559 -0
  36. package/cli/test-run-checks.mjs +603 -0
  37. package/cli/test-worktree.mjs +520 -0
  38. package/cli/thread.mjs +4 -0
  39. package/cli/tidy.mjs +2 -2
  40. package/cli/toolbox.mjs +36 -5
  41. package/cli/workspace.mjs +4 -1
  42. package/cli/worktree-record.mjs +53 -0
  43. package/cli/worktree.mjs +379 -0
  44. package/package.json +3 -3
  45. package/skills/sdlc/config.yaml +1 -1
  46. package/skills/sdlc/module-help.csv +1 -1
  47. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  48. package/skills/yad-change/SKILL.md +3 -0
  49. package/skills/yad-checks/SKILL.md +34 -5
  50. package/skills/yad-checks/references/check-gates.md +69 -10
  51. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  52. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  53. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  54. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  55. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  56. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  57. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  58. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  59. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  60. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  61. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  62. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  63. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  64. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  65. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  66. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  67. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  68. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  69. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  70. package/skills/yad-commit/SKILL.md +4 -2
  71. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  72. package/skills/yad-docs/templates/app/package.json +2 -2
  73. package/skills/yad-engineer-review/SKILL.md +45 -20
  74. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  75. package/skills/yad-epic/references/state-schema.md +75 -16
  76. package/skills/yad-implement/SKILL.md +75 -13
  77. package/skills/yad-implement/references/implement-conventions.md +8 -1
  78. package/skills/yad-implement/templates/.gitmessage +3 -0
  79. package/skills/yad-open-pr/SKILL.md +21 -0
  80. package/skills/yad-pr-template/SKILL.md +6 -2
  81. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  82. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  83. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  84. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  85. package/skills/yad-product-bridge/SKILL.md +14 -1
  86. package/skills/yad-product-bridge/references/bridge.md +5 -2
  87. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  88. package/skills/yad-reconcile/SKILL.md +9 -3
  89. package/skills/yad-review-gate/SKILL.md +4 -0
  90. package/skills/yad-review-gate/references/gating.md +26 -1
  91. package/skills/yad-run/SKILL.md +52 -28
  92. package/skills/yad-run/references/run-loop.md +42 -21
  93. package/skills/yad-spec/SKILL.md +137 -16
  94. package/skills/yad-spec/references/spec-handoff.md +50 -3
  95. package/skills/yad-status/SKILL.md +7 -0
  96. package/skills/yad-stories/references/story-schema.md +1 -1
@@ -16,6 +16,11 @@ the Product.
16
16
  - Run **inside the code repo** under `{project-root}/demo-repos/<repo>/` (or pass `--repo <name>` to
17
17
  resolve it from `.sdlc/repos.json`). The branch must be the task branch, not the default branch.
18
18
  - **Platform** is detected from the `origin` remote (or the registry / `--platform`).
19
+ - **Grouped PR (#350)** — several small tasks of ONE story may go in one PR/MR, each commit keeping its own
20
+ `Task:` line. `yad open-pr` reads the tasks from the commits, lists them all in the body's Story / task
21
+ line, and warns (never refuses) when the change is over the Product's `group_limit` (default 200 lines,
22
+ 10 files, from the merge base) or the tasks belong to more than one story. Each task ships from the PR:
23
+ `yad build ship <story> --task <T> --repo <r> --pr <n>` for each.
19
24
  - **Title** — defaults to the last commit subject (one atomic task = one branch = one PR/MR), so it
20
25
  follows the same Conventional-Commits style and passes the `pr-title` gate. Override with `--title`.
21
26
  - **Body** — the committed template (`.github/pull_request_template.md` /
@@ -83,6 +88,22 @@ The CLI pushes the branch (sets upstream, the user's own auth), fills the templa
83
88
  PR/MR with the assignee set and no reviewers requested. It prints the base it resolved and where that
84
89
  came from.
85
90
 
91
+ **`--via auto` — opened on the standing approval (#356).** When the project set
92
+ `yad dial open-pr --to auto`, the `yad-run` skill opens a task's PR/MR without asking, with
93
+ `yad open-pr --via auto`. Before it pushes anything it refuses unless: this is a task branch in a code repo
94
+ the Product registers, carrying exactly one task of this Product (`EP-<slug>-S<n>-T<n>`, in any case and under
95
+ any folders; `--task` only confirms it — a branch carrying none is refused); the dial is auto and the
96
+ kill switch is off; and the lane's `checks` step is passed **now**, and each task's newest
97
+ close names it (the close, or its run — close it with `--task`) with a trust run that passed (`checks=pass`)
98
+ and was not rejected. A step reopened and not closed again holds every task. A grouped PR (#350) — its
99
+ commits carry several small tasks of the branch's story — is opened only when every task passes, and is
100
+ recorded once per task. The base is fetched first, so tasks merged since the last fetch are not counted; a
101
+ failed fetch refuses `--via auto`. A `--task` other than the branch's
102
+ task is refused, and so is a Product branch. A task already opened this way, or one that has already shipped (a follow-up is opened by a person), is refused. Once open, the PR/MR is
103
+ recorded on the lane (`opened`: task, number, url, the run, who, when) — commit it from the Product with
104
+ `yad checkpoint --push`. Without `--via` (or `--via human`) it opens as before and records nothing. The
105
+ merge is always a person's.
106
+
86
107
  The non-default-base warning is **advisory — it does not block, and the PR/MR is already open by the
87
108
  time you read it.** If the base was intended (a stacked PR, a release branch), carry on. If it was
88
109
  not, do **not** just retarget the open PR — that leaves the AI first pass skipped. Close it, fix the
@@ -35,7 +35,10 @@ routing helper.
35
35
  the template" (#164). Both GitLab templates say so in a comment and keep `## Summary` /
36
36
  `## Impact & Risk` / `## Checklist` (Product: `## Artifact under review` / `## Impact & Risk (front-half)`
37
37
  / `## Checklist`) early, so a truncated body still passes. Long narrative goes **after** them.
38
- Sections may be reordered freely; deleting one fails the gate. GitHub is unaffected.
38
+ Sections may be reordered freely; deleting one fails the gate. GitHub is unaffected. Since #343 the gate
39
+ reads a cut description again in full from the merge request API, with the `GITLAB_TOKEN` CI/CD
40
+ variable (`read_api`) or the job's own token where GitLab allows it — so order matters only when
41
+ neither can read it, as in a fork's pipeline (see `yad-checks` `references/check-gates.md`).
39
42
  - **Installed code-repo templates are yad-managed.** `yad update` rewrites them on upgrade (the Product
40
43
  variants under `templates/product/` are copied by hand in Step 2 and are not managed). An edit yad can
41
44
  prove — the file's sha differs from the one it recorded when it wrote the template — is reported as
@@ -45,7 +48,8 @@ routing helper.
45
48
  - The Impact & Risk block reuses the conventions of earlier steps: the `Task: <story>-<task>` trailer
46
49
  (`yad-implement`), the contract surface (`yad-architecture` / contract-check), and the
47
50
  approver count (`yad-review-gate`).
48
- - **PR/MR title.** One atomic task = one branch = one PR/MR, so the title **defaults to that task's
51
+ - **PR/MR title.** One atomic task = one branch = one PR/MR (or a group of small tasks of one story, #350,
52
+ whose body lists every task), so the title **defaults to that task's
49
53
  commit subject** and follows the same Conventional Commits style — `<type>: <lowercase imperative
50
54
  description, no trailing period>`, proper nouns/acronyms keep their case (`config.yaml`
51
55
  `build.pr_title_style`; see `CONTRIBUTING.md`). Because PRs are squash-merged, the title becomes the
@@ -82,12 +82,90 @@ GITLAB_DESC_LIMIT=2700
82
82
  # locale-independent way: every byte that is NOT a continuation byte (0x80-0xBF) starts one.
83
83
  RAW_CHARS="$(LC_ALL=C tr -d '\200-\277' < "$BODY" | wc -c | tr -d '[:space:]')"
84
84
 
85
+ # #343: the cut is GitLab's, not the author's, so in GitLab CI a description that reached it is read again
86
+ # IN FULL from the MR API, and that is what the gate checks. Needs a token that can read the MR: the
87
+ # GITLAB_TOKEN (or SDLC_API_TOKEN) CI/CD variable verified-commits already asks for, else the job's own
88
+ # CI_JOB_TOKEN, which GitLab's job-token access list lets read a single merge request (an older GitLab, or
89
+ # a fork's pipeline reading the target project, may not). The token goes to curl in a header file, never
90
+ # on its command line, and only to this GitLab's own API ($CI_API_V4_URL). JSON is decoded by node,
91
+ # which every yad job image has; without node, curl, a token or an answer, the cut body is checked as
92
+ # before and the note below says how to get the full one read.
93
+ FULL_READ=""
94
+ FULL_WHY=""
95
+ _fd=""
96
+ # GitLab says itself when it cut the variable (CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED); the length
97
+ # is the fallback for a GitLab that does not set it (review 1).
98
+ # A fork's MR pipeline runs in the fork: both IDs are set and differ (review 2: a branch pipeline has no
99
+ # MR project, and is not a fork).
100
+ FORK=""
101
+ if [ -n "${CI_MERGE_REQUEST_PROJECT_ID:-}" ] && [ "${CI_PROJECT_ID:-}" != "${CI_MERGE_REQUEST_PROJECT_ID}" ]; then FORK=1; fi
102
+ ADVICE=""
103
+ if [ "${GITLAB_CI:-}" = true ] && { [ "${CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED:-}" = true ] || [ "$RAW_CHARS" -ge "$GITLAB_DESC_LIMIT" ]; }; then
104
+ if [ -z "${CI_API_V4_URL:-}" ] || [ -z "${CI_MERGE_REQUEST_PROJECT_ID:-}" ] || [ -z "${CI_MERGE_REQUEST_IID:-}" ]; then
105
+ FULL_WHY="this is not a merge request pipeline"
106
+ elif ! command -v curl >/dev/null 2>&1 || ! command -v node >/dev/null 2>&1; then
107
+ FULL_WHY="curl or node is not on this runner"
108
+ else
109
+ # A runner with no usable temp folder still gets the cut body checked, and a reason (review 2).
110
+ _fd="$(mktemp -d 2>/dev/null)" || _fd=""
111
+ fi
112
+ if [ -n "$FULL_WHY" ] || [ -z "$_fd" ]; then
113
+ [ -n "$FULL_WHY" ] || FULL_WHY="this runner has no temp folder to write to"
114
+ else
115
+ # At once, so a cancelled job leaves neither the header file nor the MR's text behind (review 1). The
116
+ # trap set further down replaces this one and removes the same folder.
117
+ trap '[ -z "$_fd" ] || rm -rf "$_fd"' EXIT
118
+ _tok="${GITLAB_TOKEN:-${SDLC_API_TOKEN:-}}"
119
+ ( umask 077
120
+ if [ -n "$_tok" ]; then printf 'PRIVATE-TOKEN: %s\n' "$_tok"; else printf 'JOB-TOKEN: %s\n' "${CI_JOB_TOKEN:-}"; fi > "$_fd/h" )
121
+ _code="$(curl -sS --max-time 20 -o "$_fd/mr.json" -w '%{http_code}' -H @"$_fd/h" -- \
122
+ "${CI_API_V4_URL}/projects/${CI_MERGE_REQUEST_PROJECT_ID}/merge_requests/${CI_MERGE_REQUEST_IID}" 2>/dev/null)" || _code=""
123
+ rm -f "$_fd/h"
124
+ _decoded=""
125
+ if [ "$_code" = 200 ] && node -e '
126
+ const fs = require("fs");
127
+ let d;
128
+ try { d = JSON.parse(fs.readFileSync(process.argv[1], "utf8")).description; } catch { process.exit(3); }
129
+ if (typeof d !== "string") process.exit(3);
130
+ fs.writeFileSync(process.argv[2], d);
131
+ ' "$_fd/mr.json" "$_fd/full.md" 2>/dev/null; then
132
+ _decoded=1
133
+ fi
134
+ if [ -n "$_decoded" ]; then
135
+ BODY="$_fd/full.md"
136
+ FULL_READ=1
137
+ echo "note [pr-template]: the description reached GitLab's ${GITLAB_DESC_LIMIT}-character CI cut, so the gate read it in full from the merge request API."
138
+ else
139
+ if [ -n "${GITLAB_TOKEN:-}" ]; then _with=GITLAB_TOKEN; elif [ -n "${SDLC_API_TOKEN:-}" ]; then _with=SDLC_API_TOKEN; else _with="the job token"; fi
140
+ if [ "$_code" = 200 ]; then FULL_WHY="the merge request API answered ${_with} without a description yad could read"
141
+ else FULL_WHY="the merge request API answered ${_code:+HTTP }${_code:-nothing} to ${_with}"; fi
142
+ # What would help, by who asked and what GitLab answered (reviews 2, 3). Only a refusal is a token's
143
+ # fault; a timeout, a 5xx or an odd answer is said as it is, with no advice to change a token.
144
+ # A fork's own variable is the fork's to fix, so the token advice comes first; the fork note is for
145
+ # a refused job token only (review 4: a timeout or a 5xx in a fork is not a question of access).
146
+ if [ -n "$_tok" ]; then
147
+ case "$_code" in
148
+ 401) ADVICE="the ${_with} variable was not accepted (expired, revoked, or not a valid token here) — renew or replace it" ;;
149
+ 403) ADVICE="the ${_with} variable was refused: give it the read_api scope" ;;
150
+ 404) ADVICE="the ${_with} variable's user cannot see the merge request's project — use a token of a member with Reporter access or more" ;;
151
+ esac
152
+ else
153
+ case "$_code" in
154
+ 401|403|404)
155
+ if [ -n "$FORK" ]; then ADVICE="this pipeline runs in a fork, which cannot read the target project's merge request"
156
+ else ADVICE="set a GITLAB_TOKEN CI/CD variable (read_api, masked, not protected) so the gate reads the whole description"; fi ;;
157
+ esac
158
+ fi
159
+ fi
160
+ fi
161
+ fi
162
+
85
163
  # The Review Companion injects a `<!-- yad:trailer --> … <!-- /yad:trailer -->` briefing block (and
86
164
  # `<!-- yad:noblock -->` notes) into the description. Strip those before the template check so the
87
165
  # AI-generated prose can never hide a required section heading or be mistaken for the `Risk level:`
88
166
  # value (the trailer is prepended, so an unstripped "risk level" mention would win `head -1`).
89
- STRIPPED="$(mktemp)"
90
- trap 'rm -f "$STRIPPED"' EXIT
167
+ STRIPPED="$(mktemp 2>/dev/null)" || { echo "FAIL [pr-template]: no temp folder to write to (TMPDIR=${TMPDIR:-/tmp}) — the description cannot be checked."; exit 1; }
168
+ trap 'rm -f "$STRIPPED"; [ -z "$_fd" ] || rm -rf "$_fd"' EXIT
91
169
  sed '/<!-- yad:trailer -->/,/<!-- \/yad:trailer -->/d; /<!-- yad:noblock -->/d' "$BODY" > "$STRIPPED"
92
170
  BODY="$STRIPPED"
93
171
 
@@ -144,7 +222,7 @@ if [ "$PROFILE" = product ]; then
144
222
  # which must go through a review/EP-* PR. Without this guard a non-review head could carry an
145
223
  # artifact change past the Shape review with only the code template.
146
224
  if artifact_changed; then
147
- echo "FAIL [pr-template]: head '${HEADREF}' changes Shape artifacts (epics/** or foundation/**) but is not a review/EP-* branch — artifact changes must go through a review PR."
225
+ echo "FAIL [pr-template]: head '${HEADREF}' changes Shape artifacts (epics/** or foundation/**) but is not a review/EP-* branch — move those changes to a review/<epic>/<artifact> branch, like review/EP-<slug>/architecture (review/EP-foundation/foundation for foundation/), and run yad open-pr from it, which pushes the branch and opens the review PR; or drop them from this PR."
148
226
  rc=1
149
227
  else
150
228
  check_code_body; KIND="product-tooling"
@@ -155,8 +233,11 @@ else
155
233
  check_code_body
156
234
  fi
157
235
 
158
- if [ "$rc" != 0 ] && [ "$RAW_CHARS" -ge "$GITLAB_DESC_LIMIT" ]; then
236
+ if [ "$rc" != 0 ] && { [ "${CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED:-}" = true ] || [ "$RAW_CHARS" -ge "$GITLAB_DESC_LIMIT" ]; } && [ -z "$FULL_READ" ]; then
159
237
  echo "NOTE [pr-template]: the description this gate read is ${RAW_CHARS} characters. On GitLab the gate reads \$CI_MERGE_REQUEST_DESCRIPTION, which is TRUNCATED at ${GITLAB_DESC_LIMIT} — a section below that cutoff is invisible here even though the MR shows it."
238
+ # A fork's pipeline gets neither the target project's variables nor a job token that may read its MR
239
+ # (review 1): only the order of the sections helps there, which the next NOTE says.
240
+ [ -z "$FULL_WHY" ] || echo "NOTE [pr-template]: the full description could not be read instead: ${FULL_WHY}${ADVICE:+ — ${ADVICE}}."
160
241
  echo "NOTE [pr-template]: if the missing section IS in your description, move the required sections above the cutoff (reorder, never delete) and push the long narrative to the end."
161
242
  fi
162
243
 
@@ -102,7 +102,7 @@ if [ "$PROFILE" = product ]; then
102
102
  # artifacts (epics/**), which must go through a review/EP-* PR. Without this guard a non-review
103
103
  # head could carry an artifact change past the Shape review with only a code title.
104
104
  if artifact_changed; then
105
- echo "FAIL [pr-title]: head '${HEADREF}' changes Shape artifacts (epics/** or foundation/**) but is not a review/EP-* branch — artifact changes must go through a review PR."
105
+ echo "FAIL [pr-title]: head '${HEADREF}' changes Shape artifacts (epics/** or foundation/**) but is not a review/EP-* branch — move those changes to a review/<epic>/<artifact> branch, like review/EP-<slug>/architecture (review/EP-foundation/foundation for foundation/), and run yad open-pr from it, which pushes the branch and opens the review PR; or drop them from this PR."
106
106
  exit 1
107
107
  fi
108
108
  # tooling only — fall through to the code convention.
@@ -1,4 +1,4 @@
1
- <!-- SDLC PR template (Phase 3 build plan §D). One atomic task per PR. -->
1
+ <!-- SDLC PR template (Phase 3 build plan §D). One atomic task per PR (or a few small tasks of one story). -->
2
2
 
3
3
  ## Summary
4
4
  <!-- What this PR does, in one or two sentences. -->
@@ -1,4 +1,4 @@
1
- <!-- SDLC MR template (Phase 3 build plan §D). One atomic task per MR. -->
1
+ <!-- SDLC MR template (Phase 3 build plan §D). One atomic task per MR (or a few small tasks of one story). -->
2
2
  <!-- GITLAB 2700-CHARACTER LIMIT: the yad-pr-template gate reads $CI_MERGE_REQUEST_DESCRIPTION, which
3
3
  GitLab truncates at 2700 characters — a heading past the cutoff reads as missing even though you
4
4
  can see it here. Keep Summary, Impact & Risk (with its filled risk-level line) and Checklist
@@ -146,8 +146,21 @@ default branch. (local mode keeps `yad gate sync` as the local writer.)
146
146
  case set the variable to a real tag. The variable lives in project settings, so it survives
147
147
  every `yad` sync. Single value only — `tags: [$VAR]` is one tag equal to the whole variable,
148
148
  not a comma-split.
149
+ - **The Node line** (#364): the job runs `image: node:${YAD_NODE_VERSION}`, `22` by default; set a
150
+ `YAD_NODE_VERSION` CI/CD variable to change it without editing the managed fragment. Leave
151
+ **Protect variable** unticked on it and on `YAD_RUNNER_TAGS` unless only protected branches run
152
+ yad jobs — a protected variable never reaches an unprotected branch's pipeline. A
153
+ **shell-executor** runner ignores `image:`: the job then runs on the runner host, which needs
154
+ `bash`, `git`, `curl` and Node with `npx` on the runner user's `PATH`. The job also installs a
155
+ pinned `glab` package with `dpkg -i` (root) and puts `jq` (and `git-lfs` when the Product uses LFS)
156
+ in `/usr/local/bin`, all `linux_amd64` builds — so a shell runner must be an x86-64 Debian-family
157
+ host whose runner user may do that; otherwise use a docker executor for this job. `yad doctor`
158
+ warns on a fragment that still runs a fixed `node:<n>` image (`YAD-CI-002`); `yad update`
159
+ replaces it — or, if `yad check` lists the file as `modified` (edited by hand), move the change
160
+ into the CI/CD variables, then run `yad update --overwrite-local`, which keeps a `.yad-orig` copy
161
+ of each file it replaces.
149
162
  - **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
163
+ hooks that fail without `git-lfs`, and the job's node image has none — so the job downloads a
151
164
  pinned `git-lfs` itself before its checkout (#327; a Product without LFS skips it). A
152
165
  `before_script` added by hand to install `git-lfs` can be removed after `yad update`.
153
166
  3. Commit the workflow to the Product. GitHub needs nothing else — the ephemeral `github.token` reads the
@@ -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
@@ -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 20, 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.
@@ -336,6 +336,10 @@ write path.
336
336
  whether approvals arrive manually or via `sync`. With no Product platform / no CLI, the gate runs local
337
337
  with no error: `yad gate approve`, `yad gate comment` and `yad gate advance` record the review in the
338
338
  engine (E112).
339
+ - **A passed gate is taken back only by `yad gate reopen`** (#322), and only before Build starts:
340
+ `yad gate reopen <epic> <step> --reason "<why>"` walks the chain back to the step and revokes the
341
+ later reviews' approvals, so each gate runs again. Never edit `state.json` or `approvals.json` by hand
342
+ to do it.
339
343
 
340
344
  ## Reference
341
345
  - 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>`. 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,8 +30,9 @@ 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:
@@ -50,8 +51,11 @@ beside it as advice and never refuses on it. The kill switch (`yad kill`) holds
50
51
 
51
52
  - `epic` / `story` / `repo` — the story and code repo to drive (ask if not provided).
52
53
  - `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).
54
+ - For `run`: `task` (the atomic task id for the `implement`/`checks` legs — when not given, the task
55
+ `yad-implement` works on; every trust run and close on those legs names it with `--task`) and `from`. The lane
56
+ is walked in order, so `from` may only name the lane's current step — or, with `task`, `implement`
57
+ once the lane is at `engineer-review`: that reopens `implement` and `checks` for the next task
58
+ (`yad build step <story> --repo <repo> implement in_progress --task <task>`).
55
59
  - For `set-dial`: `step` (a `back_steps` id), `to` — `human` | `auto` (the older `human_approve` |
56
60
  `machine_advance` mean the same two things).
57
61
  - For `kill`: `reason` (required). For `unkill`: an optional `reason`.
@@ -59,14 +63,14 @@ beside it as advice and never refuses on it. The kill switch (`yad kill`) holds
59
63
  ## On Activation
60
64
 
61
65
  ### 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
66
+ Read `config.yaml` `automation` (for `back_steps`), the story's `build-state/<story>.json`, and
67
+ `trust-log.json` (treat missing as `[]`). Resolve the code repo. If the story has **no lane for this
68
+ `repo`** (no file, or a file without that repo's entry), run `yad build start <story> --repo <repo>` **before
69
+ the loop starts**: it writes the lane from the `back_steps` defaults (all `advance: human`,
70
+ `engineer-review` locked) and never touches another repo's entry, and `yad next` reads that file to know
71
+ the lane exists. Never write `build-state/` or `trust-log/` by hand — the `yad build` commands write them
72
+ in the shape every reader expects (#346).
73
+ If this repo's entry is **`status: skipped`** (E39: the whole lane was set aside with
70
74
  `yad skip <epic> <story> --repo <repo>`, because the story needs no change in this repo), **do not drive
71
75
  it**: stop, report the recorded `record.reason`, and point at `yad unskip <epic> <story> --repo <repo>` if
72
76
  the lane is owed after all. **Never write a Build step as `skipped` or `deferred`**: a lane is skipped
@@ -91,31 +95,48 @@ Walk the steps for `repo` starting at `from`/`currentStep`. For each step:
91
95
  winning. Unbound, the engine answers `spec`→`yad-spec`, `tasks`→ the tasks leg of `yad-spec`,
92
96
  `implement`→`yad-implement`, `checks`→`yad-checks`, which is what this step used to say. Pass
93
97
  `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.
98
+ 2. **Derive trust signals & record the run** — `yad build trust <story> --repo <repo> <step> --verdict <v>
99
+ --signal <name>=<value> … --ran-by <machine|human> --json` writes the entry to its own shard with a fresh
100
+ `uid` and prints it (`ranBy: machine` if this advance was automated, else `human`) — see
101
+ `references/run-loop.md` for the derivation. Do this for *every* step run, pass or fail; the log is the
102
+ evidence base. Keep the `uid`: the closing record names it. **One exception (#357):** when the
103
+ step's skill stopped to ask its human-only questions (its first batch or a later one), the step's
104
+ output is not finished, and a draft is not output to judge: record no trust entry. Run
105
+ `yad build step <story> --repo <repo> <step> blocked [--task <task>] --reason "waiting on human
106
+ decisions: <the questions, short>"`, run `yad checkpoint --push`, and stop — skip steps 3 and 4.
107
+ **Not when the skill also hit its contract STOP** (a contract-change item in its batch): no answer
108
+ lifts that, so it is the step-4 contract-touch halt, with its trust entry, as before.
98
109
  3. **Ask the engine for the effective dial:** `yad dial <epic> <story> --repo <repo> <step> --json`, and use
99
110
  its `advance`. It is `human` whenever the step is a gate (`why: gate` — a read never refuses one), the kill switch
100
111
  is on, or `.sdlc/automation.json` cannot be read (`automationError` says so) — so never work the dial out from the files yourself.
101
112
  4. **Decide:**
102
113
  - **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
114
+ file-boundary rule), a contract-surface touch, or any ambiguity other than the human-only
115
+ questions step 2 already halted on. Run
116
+ `yad build step <story> --repo <repo> <step> blocked --reason "<the halt cause>"` (it writes the
117
+ step's `record`) — the trust entry step 2 recorded for this run is the `rejected` one, so record
118
+ 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
119
  on it reads as `todo` ("not started"), so a halt written without one is indistinguishable from a
108
120
  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>`".
121
+ - else if effective dial is **`advance: auto`** → `yad build step <story> --repo <repo> <step> done
122
+ --via auto --run <uid>` (it writes the `closed` record and moves `currentStep` on), and **continue the
123
+ loop** (this is the Step B auto-advance for `checks`).
124
+ - else (**`advance: human`**) → `yad build step <story> --repo <repo> <step> done --run <uid>`, then
125
+ **stop** and report "waiting for a human at `<next-step>`".
126
+ - On the `implement`/`checks` legs, pass `--task <task>` to `yad build trust` and `yad build step`, so
127
+ each task's run and close are kept apart (the engineer review finalizes the right one).
116
128
  - `closed` is the step's **closing record** (E18): how the lane moved past it, and which run did it.
117
129
  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
130
+ 5. **Opening the task's PR/MR (#356).** Once `checks` has closed `done` for a task — by either dial, before
131
+ you stop — ask
132
+ `yad dial open-pr --json` and use its `advance`. **`auto`** — the project's standing approval: from the
133
+ task branch, run `yad open-pr --via auto` **without asking**. It refuses (and pushes nothing) unless the
134
+ dial is auto, the `checks` step is closed now, and each task the branch's commits carry (one, or a
135
+ group of small tasks of the story — #350) has its newest close naming it (so close it with `--task <T>`)
136
+ 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.
137
+ **`human`** — stop and ask the person to approve opening it, then run `yad open-pr`. The merge is
138
+ always a person's, whatever the dial.
139
+ 6. **Always stop at `engineer-review`** (it is `locked`): hand off to `yad-engineer-review` for the human merge
119
140
  gate, which finalizes the trust verdict (confirm/override the provisional one).
120
141
 
121
142
  **Commit the machine-written state.** After each iteration's writes (the trust-log shard in 2 and the
@@ -154,6 +175,9 @@ nothing reads it, and `yad doctor` fails on one left `true`.
154
175
  and the kill switch holds every step at human.
155
176
  - **The orchestrator never changes what a step does** — it calls the existing skills and owns only the
156
177
  advance decision and the trust record.
178
+ - **One epic per folder when agents run in parallel (#115).** Each orchestrator runs in its epic's own
179
+ worktrees (`yad worktree add <epic> --all`), never in a checkout another agent is using; `yad build`
180
+ and `yad checkpoint` run from there reach that epic's Product worktree.
157
181
 
158
182
  ## Reference
159
183
  - The loop and the trust-verdict derivation: `references/run-loop.md`.
@@ -17,7 +17,7 @@ spec → tasks → implement → checks → engineer-review(locked)
17
17
  project's setting in `.sdlc/skills.json` — for every epic, or for one route only — so the loop reads
18
18
  `yad skill list --epic <epic> --json` (that epic's route, E51) once at Step 0 and
19
19
  runs every entry of that step's `skills`, in order, when it is bound to more than one. Unbound: `spec` and `tasks` are the two legs of `yad-spec` (the heavy ceremony, then the atomic
20
- `tasks.md`), `implement` is one atomic task via `yad-implement`, and `checks` is
20
+ `tasks.md`, or the tasks block of a light `spec.md`, #348), `implement` is one atomic task via `yad-implement`, and `checks` is
21
21
  `yad-checks (action: run)`. `engineer-review` is the human gate at `yad-engineer-review` — always a
22
22
  stop, never automated, and bindable like any other step.
23
23
 
@@ -25,44 +25,61 @@ stop, never automated, and bindable like any other step.
25
25
 
26
26
  ```
27
27
  cfg = config.yaml.automation
28
- bs = build-state/<story>.json.repos[<repo>] # create the FILE from defaults if absent; if the file
29
- # exists but has no entry for <repo>, add one from the
30
- # defaults — never remove an entry you did not add
28
+ bs = build-state/<story>.json.repos[<repo>] # absent: `yad build start <story> --repo <repo>` seeds it
29
+ # from the defaults (it never touches another repo's
30
+ # entry). Never write this file by hand (#346).
31
31
  if bs.status == "skipped": # E39: the whole lane was set aside with
32
32
  STOP — report bs.record.reason # `yad skip <epic> <story> --repo <repo>`; do not drive it.
33
33
  # `yad unskip <epic> <story> --repo <repo>` puts it back.
34
34
  # Never write a single Build step as skipped or deferred.
35
- step = from or bs.currentStep
35
+ step = from or bs.currentStep # from: the lane's current step only
36
+ if task and bs.currentStep == "engineer-review" and task has no close on implement:
37
+ yad build step <story> --repo <repo> implement in_progress --task <task> # reopens implement and checks
38
+ step = "implement" # for the next task
36
39
 
37
40
  while step is a Build step (not engineer-review):
38
41
  result = run_step_skill(step) # the skill(s) `yad next --json` names for this lane
42
+ # (yad-spec moves spec/tasks to in_progress itself,
43
+ # which pins Spec Kit's feature folder — #348)
44
+
45
+ if result stopped to ask human-only questions — its first batch or a later one (#357) —
46
+ and did NOT hit its contract STOP (a contract item is the contract-touch HALT below):
47
+ # the output is not finished (a draft spec.md is not output), so no trust entry — only the halt
48
+ yad build step <story> --repo <repo> <step> blocked [--task <T>] --reason "waiting on human decisions: <the questions, short>"
49
+ checkpoint; STOP and report the questions
39
50
 
40
51
  signals = derive_signals(step, result) # see "Deriving signals"
41
52
  verdict = derive_verdict(signals) # rejected | approved-with-edits | approved-unchanged
42
- uid = fresh_short_token() # e.g. `openssl rand -hex 4` — unique per run,
43
- # never reuse; a collision would fuse two runs
44
- write trust-log/<story>-<repo>-<step>-<uid>.json # ONE shard file = ONE entry (never append to a shared file)
45
- # `automation` is recorded in the OLD vocabulary (this is a history record, and `yad migrate`
46
- # deliberately leaves it alone). Read the step's dial from EITHER spelling.
47
- = { story, repo, step, uid, automation: bs.step.automation ?? old_name_for(bs.step.advance), verdict, signals, ranBy, date }
53
+ uid = `yad build trust <story> --repo <repo> <step> --verdict <verdict> --signal <name>=<value> …
54
+ --ran-by <machine|human> {--task <T>} --json`.uid # writes ONE shard, trust-log/<story>-<repo>-<step>-<uid>.json,
55
+ # with a fresh uid and the dial in force; never by hand
48
56
 
49
57
  eff = effective_dial(step, bs, cfg) # see "Effective dial"
50
58
 
51
59
  if result is a HALT (failed / scope overrun / contract touch / ambiguous):
52
60
  # `blocked` needs its `record` (E38) — that is what separates a halted lane from one that has
53
61
  # simply not started. `reason` is the halt cause you already have in hand.
54
- bs.step.status = "blocked"
55
- bs.step.record = { reason: "<check FAIL | scope overrun | contract touch | ambiguous>",
56
- by: "<platform login, else git user.name, or null>", date: "<YYYY-MM-DD>" }
57
- persist; checkpoint; STOP and report the human action needed
62
+ yad build step <story> --repo <repo> <step> blocked [--task <T>] --reason "<check FAIL | scope overrun | contract touch | ambiguous>"
63
+ checkpoint; STOP and report the human action needed
58
64
  elif eff == "auto":
59
- bs.step.status = "done"
60
- bs.step.closed = { by: "<platform login, else git user.name, or null>", date: "<YYYY-MM-DD>", via: "auto", run: uid }
61
- advance bs.currentStep to next; persist; checkpoint; continue # Step B advance
65
+ yad build step <story> --repo <repo> <step> done --via auto --run <uid> {--task <T>} # the closing record; currentStep moves on
66
+ checkpoint; if step == checks: OPEN_PR; continue # Step B advance
62
67
  else: # "human"
63
- bs.step.status = "done"
64
- bs.step.closed = { by: "<platform login, else git user.name, or null>", date: "<YYYY-MM-DD>", via: "human", run: uid }
65
- persist; checkpoint; STOP and report "waiting for human at <next>"
68
+ yad build step <story> --repo <repo> <step> done --run <uid> {--task <T>}
69
+ checkpoint; if step == checks: OPEN_PR; STOP and report "waiting for human at <next>"
70
+
71
+ # OPEN_PR — checks closed for a task, by either dial: open its PR/MR (#356)
72
+ if `yad dial open-pr --json`.advance == "auto":
73
+ yad open-pr --via auto # from the task branch; refuses unless the checks step is closed now
74
+ # and each task the commits carry (a group, #350) has its newest
75
+ # close (--task above) with a run that passed and was not rejected;
76
+ # records `opened` on the lane, once per task
77
+ else:
78
+ STOP and ask the person to approve opening it; then `yad open-pr`
79
+
80
+ # {--task <T>}: REQUIRED on the implement and checks legs, left out on spec and tasks. <T> is the `task`
81
+ # input, else the task `yad-implement` worked on. Without it the checks close names no task, and
82
+ # `yad open-pr --via auto` refuses it.
66
83
 
67
84
  # reached engineer-review: always stop, hand to yad-engineer-review (human gate, finalizes the verdict)
68
85
  ```
@@ -156,6 +173,10 @@ Reverting (`--to human`) and the kill switch are always one move.
156
173
  ## What stays human, always
157
174
 
158
175
  - `engineer-review` — the merge gate. `yad-run` always stops here and hands to `yad-engineer-review`.
176
+ Opening a task's PR/MR asks a person too, unless the project gave a standing approval with
177
+ `yad dial open-pr --to auto` (#356) — the kill switch holds it at human.
178
+ The merge stays a person's; whether it happened is asked of the platform with
179
+ `yad build merged <story> --task <T> --repo <r> --ship` (#355) — never waited for in chat.
159
180
  - The Shape steps — this loop never drives them. A Shape author step's dial may be set to auto for the
160
181
  project (`yad dial <step> --to auto`), and is only recorded until the engine runs agents (E26); every
161
182
  Shape review gate is a person.