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.
- package/CHANGELOG.md +259 -0
- package/README.md +46 -4
- package/bin/commands.mjs +9 -2
- package/bin/yad.mjs +309 -30
- package/cli/agent-guard.mjs +511 -0
- package/cli/agent-guide.mjs +83 -0
- package/cli/agent-rules.mjs +381 -0
- package/cli/argv-flags.mjs +7 -0
- package/cli/artifact-status.mjs +88 -20
- package/cli/build.mjs +1372 -0
- package/cli/checkpoint.mjs +2 -2
- package/cli/ci-check.mjs +492 -0
- package/cli/commit.mjs +1 -0
- package/cli/dial.mjs +21 -1
- package/cli/docs.mjs +7 -2
- package/cli/doctor.mjs +176 -33
- package/cli/epic-state.mjs +360 -12
- package/cli/errors.mjs +3 -0
- package/cli/find-product.mjs +36 -2
- package/cli/fold.mjs +9 -5
- package/cli/gate-local.mjs +9 -1
- package/cli/gate.mjs +364 -22
- package/cli/guide.mjs +549 -0
- package/cli/history.mjs +22 -2
- package/cli/hook.mjs +35 -4
- package/cli/index-command.mjs +2 -2
- package/cli/ledger.mjs +60 -0
- package/cli/lib.mjs +46 -0
- package/cli/lifecycle/defaults/2.json +124 -0
- package/cli/lifecycle/lifecycle.schema.json +5 -2
- package/cli/lifecycle.mjs +16 -3
- package/cli/manifest.mjs +75 -0
- package/cli/marked-block.mjs +48 -0
- package/cli/members.mjs +19 -5
- package/cli/migrate.mjs +17 -19
- package/cli/next.mjs +35 -12
- package/cli/openpr.mjs +81 -5
- package/cli/plan.mjs +326 -22
- package/cli/platform.mjs +21 -0
- package/cli/pr-list.mjs +5 -3
- package/cli/product-index.mjs +6 -3
- package/cli/product-token.mjs +186 -0
- package/cli/productcommit.mjs +33 -0
- package/cli/protection.mjs +50 -0
- package/cli/recommend.mjs +3 -1
- package/cli/reconcile.mjs +187 -26
- package/cli/repo-publish.mjs +2 -2
- package/cli/report.mjs +62 -14
- package/cli/run-checks.mjs +586 -0
- package/cli/setup.mjs +244 -25
- package/cli/ship-drift.mjs +49 -18
- package/cli/signing.mjs +377 -0
- package/cli/standup.mjs +1 -1
- package/cli/status.mjs +282 -0
- package/cli/test-agents-file.mjs +993 -0
- package/cli/test-build.mjs +1559 -0
- package/cli/test-ci-check.mjs +616 -0
- package/cli/test-guide.mjs +1267 -0
- package/cli/test-node.mjs +129 -0
- package/cli/test-run-checks.mjs +603 -0
- package/cli/test-setup-agent.mjs +352 -0
- package/cli/test-signing.mjs +524 -0
- package/cli/test-worktree.mjs +520 -0
- package/cli/thread.mjs +4 -0
- package/cli/tidy.mjs +2 -2
- package/cli/toolbox.mjs +37 -6
- package/cli/update-commit.mjs +313 -11
- package/cli/workspace.mjs +38 -10
- package/cli/worktree-record.mjs +53 -0
- package/cli/worktree.mjs +379 -0
- package/package.json +6 -4
- package/skills/sdlc/config.yaml +5 -5
- package/skills/sdlc/module-help.csv +2 -1
- package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
- package/skills/yad-change/SKILL.md +5 -1
- package/skills/yad-checks/SKILL.md +61 -12
- package/skills/yad-checks/references/check-gates.md +78 -14
- package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
- package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
- package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
- package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
- package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
- package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
- package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
- package/skills/yad-checks/templates/checks/package-manager.sh +42 -5
- package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
- package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
- package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
- package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
- package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
- package/skills/yad-checks/templates/github/yad-checks.yml +9 -9
- package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +4 -1
- package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +5 -5
- package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
- package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
- package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
- package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
- package/skills/yad-commit/SKILL.md +8 -5
- package/skills/yad-connect-repos/SKILL.md +5 -3
- package/skills/yad-connect-repos/references/code-context.md +2 -1
- package/skills/yad-connect-repos/references/repos-registry.md +2 -1
- package/skills/yad-docs/templates/app/package-lock.json +395 -106
- package/skills/yad-docs/templates/app/package.json +2 -2
- package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
- package/skills/yad-engineer-review/SKILL.md +55 -25
- package/skills/yad-engineer-review/references/ship-and-record.md +49 -12
- package/skills/yad-epic/SKILL.md +2 -1
- package/skills/yad-epic/references/state-schema.md +76 -17
- package/skills/yad-guide/SKILL.md +192 -0
- package/skills/yad-implement/SKILL.md +75 -13
- package/skills/yad-implement/references/implement-conventions.md +8 -1
- package/skills/yad-implement/templates/.gitmessage +3 -0
- package/skills/yad-open-pr/SKILL.md +21 -0
- package/skills/yad-pair-review/SKILL.md +14 -5
- package/skills/yad-pr-template/SKILL.md +6 -2
- package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
- package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
- package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
- package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
- package/skills/yad-product-bridge/SKILL.md +44 -12
- package/skills/yad-product-bridge/references/bridge.md +11 -5
- package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
- package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
- package/skills/yad-reconcile/SKILL.md +9 -3
- package/skills/yad-report/SKILL.md +15 -0
- package/skills/yad-review-companion/SKILL.md +5 -3
- package/skills/yad-review-gate/SKILL.md +16 -8
- package/skills/yad-review-gate/references/gating.md +26 -1
- package/skills/yad-run/SKILL.md +61 -33
- package/skills/yad-run/references/run-loop.md +44 -22
- package/skills/yad-spec/SKILL.md +137 -16
- package/skills/yad-spec/references/spec-handoff.md +50 -3
- package/skills/yad-status/SKILL.md +7 -0
- package/skills/yad-stories/references/story-schema.md +1 -1
- package/skills/yad-sync-repos/SKILL.md +2 -1
- 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.
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
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
|
|
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
|
|
158
|
-
`yad gate
|
|
159
|
-
`yad 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
|
|
127
|
-
|
|
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
|
|
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: "
|
|
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: "
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
50
|
-
|
|
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,
|
|
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
|
|
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
|
|
77
|
-
|
|
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,
|
|
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
|
|
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`** —
|
|
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
|
|
168
|
-
|
|
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`** —
|
|
232
|
-
`yad gate advance <epic> <artifact
|
|
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**,
|
|
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`.
|
|
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.
|
package/skills/yad-run/SKILL.md
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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`:
|
|
54
|
-
|
|
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
|
|
63
|
-
`
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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 &
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
the derivation. Do this for *every* step run, pass or fail; the log is the
|
|
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
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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`** →
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
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. **
|
|
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}
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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`.
|