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.
- package/CHANGELOG.md +170 -0
- package/README.md +4 -1
- package/bin/commands.mjs +5 -1
- package/bin/yad.mjs +167 -15
- package/cli/artifact-status.mjs +88 -20
- package/cli/build.mjs +1372 -0
- package/cli/checkpoint.mjs +2 -2
- package/cli/commit.mjs +1 -0
- package/cli/dial.mjs +21 -1
- package/cli/docs.mjs +6 -1
- package/cli/doctor.mjs +133 -26
- package/cli/epic-state.mjs +357 -9
- package/cli/errors.mjs +2 -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/history.mjs +22 -2
- package/cli/hook.mjs +3 -1
- package/cli/index-command.mjs +2 -2
- package/cli/ledger.mjs +60 -0
- package/cli/next.mjs +34 -11
- package/cli/openpr.mjs +81 -5
- 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/recommend.mjs +3 -1
- package/cli/repo-publish.mjs +2 -2
- package/cli/run-checks.mjs +586 -0
- package/cli/ship-drift.mjs +49 -18
- package/cli/standup.mjs +1 -1
- package/cli/status.mjs +282 -0
- package/cli/test-build.mjs +1559 -0
- package/cli/test-run-checks.mjs +603 -0
- package/cli/test-worktree.mjs +520 -0
- package/cli/thread.mjs +4 -0
- package/cli/tidy.mjs +2 -2
- package/cli/toolbox.mjs +36 -5
- package/cli/workspace.mjs +4 -1
- package/cli/worktree-record.mjs +53 -0
- package/cli/worktree.mjs +379 -0
- package/package.json +3 -3
- package/skills/sdlc/config.yaml +1 -1
- package/skills/sdlc/module-help.csv +1 -1
- package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
- package/skills/yad-change/SKILL.md +3 -0
- package/skills/yad-checks/SKILL.md +34 -5
- package/skills/yad-checks/references/check-gates.md +69 -10
- 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 +41 -4
- 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 +8 -8
- package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
- package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
- 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-commit/SKILL.md +4 -2
- package/skills/yad-docs/templates/app/package-lock.json +395 -106
- package/skills/yad-docs/templates/app/package.json +2 -2
- package/skills/yad-engineer-review/SKILL.md +45 -20
- package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
- package/skills/yad-epic/references/state-schema.md +75 -16
- 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-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 +14 -1
- package/skills/yad-product-bridge/references/bridge.md +5 -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-review-gate/SKILL.md +4 -0
- package/skills/yad-review-gate/references/gating.md +26 -1
- package/skills/yad-run/SKILL.md +52 -28
- package/skills/yad-run/references/run-loop.md +42 -21
- 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
|
@@ -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
|
|
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 —
|
|
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 —
|
|
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 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
|
|
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
|
|
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
|
|
@@ -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 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
|
|
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.
|
|
@@ -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`.
|
|
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.
|
package/skills/yad-run/SKILL.md
CHANGED
|
@@ -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
|
-
|
|
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`:
|
|
54
|
-
|
|
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
|
|
63
|
-
`
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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 &
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
the derivation. Do this for *every* step run, pass or fail; the log is the
|
|
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
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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`** →
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
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. **
|
|
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>] #
|
|
29
|
-
#
|
|
30
|
-
#
|
|
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 =
|
|
43
|
-
|
|
44
|
-
|
|
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
|
-
|
|
55
|
-
|
|
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
|
-
|
|
60
|
-
|
|
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
|
-
|
|
64
|
-
|
|
65
|
-
|
|
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.
|