yadflow 4.7.0 → 4.9.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 +116 -0
- package/README.md +43 -4
- package/bin/commands.mjs +5 -1
- package/bin/yad.mjs +169 -22
- package/cli/agent-guard.mjs +511 -0
- package/cli/agent-guide.mjs +83 -0
- package/cli/agent-rules.mjs +388 -0
- package/cli/argv-flags.mjs +7 -0
- package/cli/build.mjs +1 -1
- package/cli/ci-check.mjs +492 -0
- package/cli/docs.mjs +1 -1
- package/cli/doctor.mjs +148 -7
- package/cli/epic-state.mjs +3 -3
- package/cli/errors.mjs +1 -0
- package/cli/guide.mjs +549 -0
- package/cli/hook.mjs +32 -3
- 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/machine.mjs +141 -0
- 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 +1 -1
- package/cli/openpr.mjs +46 -6
- package/cli/plan.mjs +326 -22
- package/cli/preview.mjs +253 -0
- package/cli/protection.mjs +50 -0
- package/cli/reconcile.mjs +187 -26
- package/cli/repo.mjs +64 -3
- package/cli/report.mjs +62 -14
- package/cli/review.mjs +4 -0
- package/cli/setup.mjs +244 -25
- package/cli/signing.mjs +377 -0
- package/cli/story-frames.mjs +296 -0
- package/cli/test-agents-file.mjs +993 -0
- package/cli/test-ci-check.mjs +616 -0
- package/cli/test-guide.mjs +1267 -0
- package/cli/test-machine.mjs +140 -0
- package/cli/test-node.mjs +129 -0
- package/cli/test-preview.mjs +511 -0
- package/cli/test-setup-agent.mjs +352 -0
- package/cli/test-signing.mjs +524 -0
- package/cli/test-story-frames.mjs +339 -0
- package/cli/toolbox.mjs +35 -1
- package/cli/update-commit.mjs +313 -11
- package/cli/workspace.mjs +37 -12
- package/package.json +6 -4
- package/skills/sdlc/config.yaml +4 -4
- package/skills/sdlc/module-help.csv +1 -0
- package/skills/yad-change/SKILL.md +3 -2
- package/skills/yad-checks/SKILL.md +29 -9
- package/skills/yad-checks/references/check-gates.md +9 -4
- package/skills/yad-checks/templates/checks/package-manager.sh +1 -1
- package/skills/yad-checks/templates/github/yad-checks.yml +1 -1
- package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +1 -1
- package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +1 -1
- package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +1 -1
- package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -1
- package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +1 -1
- package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
- package/skills/yad-commit/SKILL.md +4 -3
- package/skills/yad-connect-design/SKILL.md +7 -4
- package/skills/yad-connect-design/references/design-context.md +23 -0
- package/skills/yad-connect-design/references/design-registry.md +3 -3
- package/skills/yad-connect-repos/SKILL.md +13 -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-overview/references/pipeline-model.md +2 -2
- package/skills/yad-engineer-review/SKILL.md +25 -7
- package/skills/yad-engineer-review/references/ship-and-record.md +7 -4
- package/skills/yad-epic/SKILL.md +2 -1
- package/skills/yad-epic/references/state-schema.md +7 -1
- package/skills/yad-guide/SKILL.md +192 -0
- package/skills/yad-implement/SKILL.md +14 -0
- package/skills/yad-open-pr/SKILL.md +5 -2
- package/skills/yad-pair-review/SKILL.md +19 -5
- package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -0
- package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -0
- package/skills/yad-product-bridge/SKILL.md +32 -13
- package/skills/yad-product-bridge/references/bridge.md +6 -3
- 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 +1 -1
- package/skills/yad-report/SKILL.md +15 -0
- package/skills/yad-review-companion/SKILL.md +9 -4
- package/skills/yad-review-gate/SKILL.md +13 -9
- package/skills/yad-review-gate/references/gating.md +1 -1
- package/skills/yad-run/SKILL.md +10 -6
- package/skills/yad-run/references/run-loop.md +2 -1
- package/skills/yad-spec/SKILL.md +21 -0
- package/skills/yad-stories/SKILL.md +22 -0
- package/skills/yad-stories/references/story-schema.md +1 -0
- package/skills/yad-sync-repos/SKILL.md +2 -1
- package/skills/yad-ui/SKILL.md +7 -2
|
@@ -35,8 +35,8 @@ in CI on every PR/MR and must pass before merge (build plan §C). Each is a smal
|
|
|
35
35
|
epic's ledger directory to resolve — a Product that is simply not checked out still defers, as before,
|
|
36
36
|
except on a repo's **first spec** (no `link.md` on the base names a Product): there a slice change whose
|
|
37
37
|
`product-repo` reaches nothing **fails** (E119), because the PR chose that value itself. Where the
|
|
38
|
-
Product lives is a repo fact once
|
|
39
|
-
the
|
|
38
|
+
Product lives is a repo fact once `.sdlc/product-link.json` is on the code repo's default branch
|
|
39
|
+
(E120; `yad check --fix --open-pr`, merged by a person, or `--push` after the person's yes): the gates read it from the base first, and `checks/product-checkout.sh` clones
|
|
40
40
|
the Product there in CI when the `YAD_PRODUCT_TOKEN` secret is set (see `references/check-gates.md`).
|
|
41
41
|
A missing token on a PR that is not from a fork is a `WARNING` in CI, and a token that expires within
|
|
42
42
|
30 days is warned about there too (#345); `yad doctor` reports where each code repo's CI gets it.
|
|
@@ -118,6 +118,16 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
|
|
|
118
118
|
`templates/hooks/ledger-guard-cursor.mjs` and a `preToolUse` entry in `.cursor/hooks.json`.
|
|
119
119
|
Fails OPEN; see "Step 2b" below. Every hook is a Node script the entry runs as `node <script>`, so
|
|
120
120
|
it needs no bash and no execute bit and runs on Windows too (E113).
|
|
121
|
+
- `templates/hooks/agent-guard.mjs` → the Product (`hooks/agent-guard.mjs`) **and every connected code
|
|
122
|
+
repo** (`checks/agent-guard.mjs`, E158b), in **both** ledger modes (E158): the harness
|
|
123
|
+
hook that runs `yad hook agent-guard` before every shell command an AI agent sends. It refuses a yad
|
|
124
|
+
command only the person may run (`gate approve`, `comment`, `advance`, `reopen`, `commit --manual`),
|
|
125
|
+
approving or merging a PR/MR (`gh pr review --approve`, `gh pr merge`, `glab mr approve|merge|accept`, or the
|
|
126
|
+
same through `gh api`/`glab api`), skipping the git hooks (`git commit --no-verify` or `-n`,
|
|
127
|
+
`YAD_HOOK_DISABLE=…`, `core.hooksPath`), and a force push (`--force`, `-f`, `--force-with-lease`, `--force-if-includes`, `--mirror`, a `+` refspec), and tells the agent to hand it to the person. Wired as a `PreToolUse` entry on `Bash` in
|
|
128
|
+
`.claude/settings.json` and a `beforeShellExecution` entry in `.cursor/hooks.json` of each of those
|
|
129
|
+
folders, so it runs in a session opened at either. Fails OPEN, and is a speed bump, not
|
|
130
|
+
proof: a command inside a script is not seen, and Codex has no hooks.
|
|
121
131
|
- `templates/hooks/yad-capture.mjs` → **Product-only**, in **both** ledger modes (E43): the post-edit
|
|
122
132
|
harness hook that runs `yad capture --hook`, which snapshots every changed Shape artifact onto the
|
|
123
133
|
person's private `yad/wip/<name>/<epic>` branches without touching the checkout. Wired as a
|
|
@@ -193,6 +203,11 @@ Copy from this skill's `templates/`:
|
|
|
193
203
|
human to paste (graceful degradation — never guess-edit a pipeline you cannot parse).
|
|
194
204
|
- The legacy standalone `templates/gitlab/.gitlab-ci.yml` is retained only for a clean greenfield repo
|
|
195
205
|
that prefers a single self-contained file; the include path above is the default.
|
|
206
|
+
- **CI/CD variables, tokens and branch protection are the person's (E158).** An AI agent gives them
|
|
207
|
+
the steps below, never sets one itself, and confirms by reading once they say it is done.
|
|
208
|
+
`yad doctor` reads branch protection and where `YAD_PRODUCT_TOKEN` is set; it cannot read the
|
|
209
|
+
`YAD_RUNNER_TAGS` or `YAD_NODE_VERSION` values, so for those, ask the person and take the next
|
|
210
|
+
green pipeline as the proof. It runs `yad update --overwrite-local` only when the person asks.
|
|
196
211
|
- **Tag-locked runners** (`run_untagged: false`, common on self-hosted): the fragment's jobs run a
|
|
197
212
|
docker image, so set a `YAD_RUNNER_TAGS` CI/CD variable (e.g. `dind_runner`) to route them — every
|
|
198
213
|
GitLab fragment's jobs carry `tags: [$YAD_RUNNER_TAGS]`. When unset, current GitLab (≥15) drops the
|
|
@@ -207,14 +222,15 @@ Copy from this skill's `templates/`:
|
|
|
207
222
|
project variable wins over the fragment's value, so the fragment itself is never edited.
|
|
208
223
|
- **Shell-executor runners** ignore `image:`. The jobs then run on the runner host as they are, so
|
|
209
224
|
the host needs `bash`, `git`, `curl` (the signature gates read the GitLab API with it; without it
|
|
210
|
-
every commit reads as unverified) and Node (any current
|
|
225
|
+
every commit reads as unverified) and Node (any current 22 or 24 line — for example from nvm)
|
|
211
226
|
on the runner user's `PATH`, plus whatever the repo's own build needs (Corepack, pnpm, …) for
|
|
212
227
|
`build-test-lint`. `YAD_NODE_VERSION` has no effect there. Point `YAD_RUNNER_TAGS` at that
|
|
213
228
|
runner's tag.
|
|
214
229
|
- **Do not hand-edit the fragments to fit a runner.** They are managed bytes: `yad check` reports a
|
|
215
230
|
hand-edited one as `modified`, and a plain `yad update` leaves it alone — so it never receives a
|
|
216
231
|
fix again. Both runner settings above are CI/CD variables, so no edit is needed: move the
|
|
217
|
-
customisation into them
|
|
232
|
+
customisation into them (the person's, above), then, when the person asks, run
|
|
233
|
+
`yad update --overwrite-local` to restore the fragment (it keeps
|
|
218
234
|
a `.yad-orig` copy of the edited one first). `yad doctor` warns when a wired
|
|
219
235
|
fragment has no `tags:` (`YAD-CI-001`) or still runs a fixed `node:<n>` image (`YAD-CI-002`, an
|
|
220
236
|
install from before the variable — `yad update` replaces it).
|
|
@@ -228,7 +244,9 @@ Copy from this skill's `templates/`:
|
|
|
228
244
|
|
|
229
245
|
Re-running `wire` is **idempotent** — markers (`# yad-managed: yad-checks`,
|
|
230
246
|
`# yad-managed-include: yad-checks`) and the include-entry check make a second run a no-op.
|
|
231
|
-
|
|
247
|
+
The wiring belongs on the repo's default branch (it is shared infrastructure, not a task diff). Get it
|
|
248
|
+
there with `yad check --fix --open-pr`, which opens a PR/MR without asking; a commit or push straight
|
|
249
|
+
to the default branch needs the person's yes each time (E158).
|
|
232
250
|
|
|
233
251
|
**The Product is wired the same way.** `repo: product` wires the Product repo itself (platform from `.sdlc/product.json`)
|
|
234
252
|
with a Product-flavored gate set — see "Wiring the Product" in `references/check-gates.md`.
|
|
@@ -236,7 +254,9 @@ with a Product-flavored gate set — see "Wiring the Product" in `references/che
|
|
|
236
254
|
**The Product also gets the agent guardrail** (see below): `templates/hooks/ledger-guard.mjs` →
|
|
237
255
|
`<product>/hooks/ledger-guard.mjs`, plus the `PreToolUse` entry in `.claude/settings.json`. A project
|
|
238
256
|
whose targets include `.cursor` also gets `templates/hooks/ledger-guard-cursor.mjs` and a `preToolUse`
|
|
239
|
-
entry in `.cursor/hooks.json`.
|
|
257
|
+
entry in `.cursor/hooks.json`. Every Product, in both ledger modes, also gets the agent guard
|
|
258
|
+
(`templates/hooks/agent-guard.mjs`, above), which stops an agent from running an approval or a force
|
|
259
|
+
push. `yad setup` and `yad check --fix` install them; nothing by hand.
|
|
240
260
|
|
|
241
261
|
### Step 2b — the agent guardrail (harness hooks, verified mode only)
|
|
242
262
|
The CI gates speak at CI time. That is too late for one failure the field kept hitting (#171): in
|
|
@@ -272,9 +292,9 @@ file-editing tool call and refuses the write up front, naming the command that o
|
|
|
272
292
|
- **A no-op with a local ledger.** There the ledger is locally owned and the hand-edit the authoring
|
|
273
293
|
skills describe is *correct*, so nothing is wired and nothing is blocked.
|
|
274
294
|
- **It fails OPEN** — no `yad`, no Product, an unreadable config, an unparseable payload all ALLOW, with
|
|
275
|
-
a note on stderr. `ledger-guard` in CI fails *closed* and remains the authority.
|
|
276
|
-
|
|
277
|
-
"<why>"` (E49) — never the agent
|
|
295
|
+
a note on stderr. `ledger-guard` in CI fails *closed* and remains the authority. A PERSON can skip it
|
|
296
|
+
for one command with `YAD_HOOK_DISABLE=1`; never the agent (a NEVER rule, and the agent guard refuses it). A PERSON who must commit a ledger change anyway uses `yad commit --manual --reason
|
|
297
|
+
"<why>"` (E49) — never the agent, even when asked: it gives the person the exact command (E158).
|
|
278
298
|
- **Known gaps** (both caught by the CI gate instead): a `Bash` tool call (`sed -i epics/…`) is not
|
|
279
299
|
intercepted — matching it would mean parsing shell; and the hook arms sessions **rooted at the
|
|
280
300
|
Product**, since a harness reads hooks from its own project root — a session opened at the workspace
|
|
@@ -272,7 +272,7 @@ Every gate stops on its failure except **risk-map**, which is advisory: there a
|
|
|
272
272
|
pinned Node. A declared `packageManager` needs
|
|
273
273
|
Corepack, which ships with Node 18 through 24 (Node 25+ dropped it) and, before 18.20.7 / 20.19 /
|
|
274
274
|
22.14, carries registry keys too old to verify anything published since 2025 — so the override
|
|
275
|
-
should stay on a current
|
|
275
|
+
should stay on a current 22 or 24 line (or install a current Corepack first). The installer
|
|
276
276
|
checks for the binary and wraps `corepack prepare`, so both an absent and a stale Corepack fail
|
|
277
277
|
with that guidance instead of a bare "command not found" or "Cannot find matching keyid".
|
|
278
278
|
- Tests must actually exercise behavior (build plan §C) — an empty or trivially-passing suite does not
|
|
@@ -702,11 +702,15 @@ workflows run `checks/product-checkout.sh` (wired into every code repo). It read
|
|
|
702
702
|
`YAD_PRODUCT_TOKEN` secret is set, clones the Product's `default_branch` (depth 1; the remote's own default when the record names
|
|
703
703
|
none) into the record's `path`. To turn it on:
|
|
704
704
|
|
|
705
|
-
1. From the Product, run `yad check --fix --
|
|
706
|
-
connected code repo and
|
|
705
|
+
1. From the Product, run `yad check --fix --open-pr`: it writes `.sdlc/product-link.json` into each
|
|
706
|
+
connected code repo and opens a PR/MR with it, which a person merges. (`--push` commits it straight
|
|
707
|
+
to the default branch instead; an agent asks the person every time before that, E158.) Set the Product's `git_url` in its
|
|
707
708
|
`.sdlc/product.json` first (`yad setup` fills it from the `origin` remote). On a Product that has only
|
|
708
709
|
`.sdlc/hub.json`, set it there, and never create a `product.json` beside it by hand; when both exist,
|
|
709
710
|
run `yad migrate --apply --keep product` after the edit.
|
|
711
|
+
Steps 2 and 3 are the person's: an AI agent gives them these steps and never makes or sets the token
|
|
712
|
+
itself, then confirms by reading (`yad doctor`) once they say it is done (E158).
|
|
713
|
+
|
|
710
714
|
2. Make a token that can **read** the Product repository — on GitHub a fine-grained personal access
|
|
711
715
|
token or a GitHub App token with `contents: read` on that one repo (the workflow's own `GITHUB_TOKEN`
|
|
712
716
|
cannot read another private repo); on GitLab a project or group access token with `read_repository`.
|
|
@@ -947,7 +951,8 @@ logic is unit-tested (`cli/hook.mjs`, `cli/test.mjs`; the scripts in `cli/test-h
|
|
|
947
951
|
an unreadable `product.json` / `hub.json`, an unparseable payload, a `yad` that errors — every one of them ALLOWS,
|
|
948
952
|
with a note on stderr. A local guardrail that failed closed would brick an agent's ability to edit
|
|
949
953
|
anything the moment an install went sideways. The CI gate fails **closed** and is what actually
|
|
950
|
-
protects the ledger; this only shortens the feedback loop.
|
|
954
|
+
protects the ledger; this only shortens the feedback loop. A person can skip it for one command with
|
|
955
|
+
`YAD_HOOK_DISABLE=1`; never the agent (a NEVER rule, and the agent guard refuses it).
|
|
951
956
|
The door for a PERSON is `yad commit --manual --reason "<why>"` (E49): it skips the local hook for that
|
|
952
957
|
one commit and records the reason as a `Ledger-Override:` trailer. `ledger-guard` in CI still FAILS the
|
|
953
958
|
commit — anyone can type a trailer — and prints the reason under the FAIL. Each line starts with the commit's sha, and every control character (a
|
|
@@ -14,7 +14,7 @@ readonly YAD_NPM_SHRINKWRAP="npm-shrinkwrap.json"
|
|
|
14
14
|
# 20.19 / 22.14 — predates the 2025 npm registry key rotation and rejects anything published since
|
|
15
15
|
# with a raw "Cannot find matching keyid". A declared packageManager without a working Corepack must
|
|
16
16
|
# say so instead of dying with "command not found" or that error in the middle of the job.
|
|
17
|
-
readonly YAD_COREPACK_LINES="set YAD_NODE_VERSION to a current
|
|
17
|
+
readonly YAD_COREPACK_LINES="set YAD_NODE_VERSION to a current 22 or 24 line, or install a current Corepack first (npm install -g corepack)"
|
|
18
18
|
yad_require_corepack() {
|
|
19
19
|
if command -v corepack >/dev/null 2>&1; then return 0; fi
|
|
20
20
|
echo "FAIL [package-manager]: package.json#packageManager is set but corepack is not on PATH (Node 25+ no longer bundles it) — $YAD_COREPACK_LINES." >&2
|
|
@@ -53,7 +53,7 @@ jobs:
|
|
|
53
53
|
if: github.event.action != 'edited'
|
|
54
54
|
env:
|
|
55
55
|
YAD_TEST_MAX_WORKERS: "2" # cap jest/vitest test workers in CI; ignored by other runners
|
|
56
|
-
YAD_NODE_VERSION: ${{ vars.YAD_NODE_VERSION || '22' }} # repo variable; a current
|
|
56
|
+
YAD_NODE_VERSION: ${{ vars.YAD_NODE_VERSION || '22' }} # repo variable; a current 22 or 24 line (Node 25+ has no Corepack; 18 and 20 are end of life)
|
|
57
57
|
NX_BASE: ${{ github.event.pull_request.base.sha }}
|
|
58
58
|
NX_HEAD: ${{ github.event.pull_request.head.sha }}
|
|
59
59
|
COREPACK_HOME: ${{ github.workspace }}/.corepack-cache # pinned-manager downloads, cached below
|
|
@@ -15,7 +15,7 @@ default:
|
|
|
15
15
|
|
|
16
16
|
variables:
|
|
17
17
|
GIT_DEPTH: "0" # full history so the gates can diff against the target branch
|
|
18
|
-
YAD_NODE_VERSION: "22" # override with a project/group CI variable (a current
|
|
18
|
+
YAD_NODE_VERSION: "22" # override with a project/group CI variable (a current 22 or 24 line; Node 25+ has no Corepack; 18 and 20 are end of life)
|
|
19
19
|
NX_BASE: $CI_MERGE_REQUEST_DIFF_BASE_SHA
|
|
20
20
|
NX_HEAD: $CI_COMMIT_SHA
|
|
21
21
|
|
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
image: node:${YAD_NODE_VERSION}
|
|
24
24
|
variables:
|
|
25
25
|
# A project/group CI/CD variable overrides a YAML value, so YAD_NODE_VERSION can be changed in
|
|
26
|
-
# project settings without editing the managed fragment (a current
|
|
26
|
+
# project settings without editing the managed fragment (a current 22 or 24 line; Node 25+ has no Corepack).
|
|
27
27
|
YAD_NODE_VERSION: "22"
|
|
28
28
|
NX_BASE: $CI_MERGE_REQUEST_DIFF_BASE_SHA
|
|
29
29
|
NX_HEAD: $CI_COMMIT_SHA
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
image: node:${YAD_NODE_VERSION}
|
|
21
21
|
variables:
|
|
22
22
|
# A project/group CI/CD variable overrides this YAML value, so the Node line can be changed in project
|
|
23
|
-
# settings without editing the managed fragment (a current
|
|
23
|
+
# settings without editing the managed fragment (a current 22 or 24 line). A shell-executor runner
|
|
24
24
|
# ignores `image:` — Node must then be on the runner host's PATH, and this value has no effect.
|
|
25
25
|
YAD_NODE_VERSION: "22"
|
|
26
26
|
# Runner selection: set the YAD_RUNNER_TAGS CI/CD variable (e.g. `dind_runner`) to route these jobs on
|
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
variables:
|
|
24
24
|
GIT_DEPTH: "0" # full history so the gates can diff the pushed range
|
|
25
25
|
# A project/group CI/CD variable overrides this YAML value, so the Node line can be changed in project
|
|
26
|
-
# settings without editing the managed fragment (a current
|
|
26
|
+
# settings without editing the managed fragment (a current 22 or 24 line). A shell-executor runner
|
|
27
27
|
# ignores `image:` — Node must then be on the runner host's PATH, and this value has no effect.
|
|
28
28
|
YAD_NODE_VERSION: "22"
|
|
29
29
|
before_script:
|
|
@@ -21,7 +21,7 @@ yad-product-verified-commits:
|
|
|
21
21
|
variables:
|
|
22
22
|
GIT_DEPTH: "0" # full history so the gate can diff against the target branch
|
|
23
23
|
# A project/group CI/CD variable overrides this YAML value, so the Node line can be changed in project
|
|
24
|
-
# settings without editing the managed fragment (a current
|
|
24
|
+
# settings without editing the managed fragment (a current 22 or 24 line). A shell-executor runner
|
|
25
25
|
# ignores `image:` — Node must then be on the runner host's PATH, and this value has no effect.
|
|
26
26
|
YAD_NODE_VERSION: "22"
|
|
27
27
|
rules:
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
// agent-guard HARNESS HOOK (E158) — before an AI agent's shell command runs, refuse a yad command only the
|
|
2
|
+
// person may run (an approval; a gate comment, advance or reopen; `commit --manual`), a PR/MR approval or merge
|
|
3
|
+
// (`gh`, `glab`), skipping the git hooks (`--no-verify` or `-n`, `YAD_HOOK_DISABLE`, `core.hooksPath`), or a force
|
|
4
|
+
// push, and say what to do instead: ask the person to run it themselves.
|
|
5
|
+
//
|
|
6
|
+
// This file is only the ADAPTER. It locates `yad` and hands the payload to `yad hook agent-guard`, which
|
|
7
|
+
// holds the decision (cli/agent-guard.mjs). ONE script serves both harnesses, and answers in the protocol
|
|
8
|
+
// the payload names:
|
|
9
|
+
//
|
|
10
|
+
// Claude Code `PreToolUse`, matcher `Bash`: exit 0 allows, exit 2 denies with the reason on stderr
|
|
11
|
+
// Cursor `beforeShellExecution`: a permission hook — a JSON verdict on stdout, ALWAYS, since an
|
|
12
|
+
// empty or off-schema answer blocks the command
|
|
13
|
+
//
|
|
14
|
+
// A SPEED BUMP, NOT PROOF: a command hidden in a script or an alias is not seen. The platform, and CI's
|
|
15
|
+
// ledger guard, are what prove an approval. Codex has no hooks: there only the rules in AGENTS.md apply.
|
|
16
|
+
//
|
|
17
|
+
// A NODE SCRIPT (E113), importing nothing outside Node, because it runs from the Product (`hooks/`) or a
|
|
18
|
+
// connected code repo (`checks/`, E158b), where yadflow may not be installed at all.
|
|
19
|
+
//
|
|
20
|
+
// FAIL-OPEN: if no `yad` can be found, or it cannot run, the command is ALLOWED and this says why on stderr.
|
|
21
|
+
import { spawnSync } from 'node:child_process';
|
|
22
|
+
import fs from 'node:fs';
|
|
23
|
+
import path from 'node:path';
|
|
24
|
+
import { fileURLToPath } from 'node:url';
|
|
25
|
+
|
|
26
|
+
// ---- yad-resolve (the same block in every hooks/*.mjs; a test keeps the copies identical) ----------
|
|
27
|
+
// The Product root is this script's grandparent — `<product>/hooks/<script>.mjs` — found from the
|
|
28
|
+
// script's OWN location, never from the harness's working directory or its project-root variable
|
|
29
|
+
// (whose form on Windows, `C:\…` or `/c/…`, no harness documents). `realpathSync` so a script reached
|
|
30
|
+
// through a symbolic link still finds its own Product.
|
|
31
|
+
const PRODUCT_ROOT = path.dirname(path.dirname(fs.realpathSync(fileURLToPath(import.meta.url))));
|
|
32
|
+
const IS_WINDOWS = process.platform === 'win32';
|
|
33
|
+
|
|
34
|
+
// A command found on PATH, or null. On Windows the npm launchers are `.cmd` files.
|
|
35
|
+
function onPath(name) {
|
|
36
|
+
const exts = IS_WINDOWS ? ['.cmd', '.exe', ''] : [''];
|
|
37
|
+
for (const dir of (process.env.PATH || '').split(path.delimiter)) {
|
|
38
|
+
if (!dir) continue;
|
|
39
|
+
for (const ext of exts) {
|
|
40
|
+
const full = path.join(dir, name + ext);
|
|
41
|
+
try { if (fs.statSync(full).isFile()) return full; } catch { /* not here */ }
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
return null;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
// Windows cannot start a `.cmd` launcher without a shell (Node refuses since 18.20.2), so those run
|
|
48
|
+
// through one, each word in double quotes. A Windows path cannot hold a `"`, so the quoting is whole.
|
|
49
|
+
const quoteForCmd = (word) => `"${String(word).replace(/"/g, '')}"`;
|
|
50
|
+
|
|
51
|
+
// How to run `yad`, cheapest and most specific first: an explicit override, then the copy installed in
|
|
52
|
+
// this Product, then `yad` on PATH, then a network-free npx. `--no-install` matters — a hook runs on
|
|
53
|
+
// every tool call and must never pause an agent to download a package. Returns
|
|
54
|
+
// `{ file, args, shell }` or null.
|
|
55
|
+
function resolveYad() {
|
|
56
|
+
// YAD_BIN is commonly an interpreter plus a script ("node /path/to/yad.mjs"). Split on spaces, with a
|
|
57
|
+
// double-quoted word kept whole — Node on Windows usually lives under `C:\Program Files\`.
|
|
58
|
+
const override = [...(process.env.YAD_BIN || '').matchAll(/"([^"]*)"|(\S+)/g)].map((m) => m[1] ?? m[2]).filter(Boolean);
|
|
59
|
+
if (override.length) {
|
|
60
|
+
const [file, ...args] = override;
|
|
61
|
+
return { file, args, shell: IS_WINDOWS && /\.(cmd|bat)$/i.test(file) };
|
|
62
|
+
}
|
|
63
|
+
const local = path.join(PRODUCT_ROOT, 'node_modules', 'yadflow', 'bin', 'yad.mjs');
|
|
64
|
+
if (fs.existsSync(local)) return { file: process.execPath, args: [local], shell: false };
|
|
65
|
+
const yad = onPath('yad');
|
|
66
|
+
if (yad) {
|
|
67
|
+
if (!IS_WINDOWS || !/\.(cmd|bat)$/i.test(yad)) return { file: yad, args: [], shell: false };
|
|
68
|
+
// An npm global install puts the package beside its launcher: run the script with this Node
|
|
69
|
+
// rather than through a shell whenever it is there.
|
|
70
|
+
const script = path.join(path.dirname(yad), 'node_modules', 'yadflow', 'bin', 'yad.mjs');
|
|
71
|
+
if (fs.existsSync(script)) return { file: process.execPath, args: [script], shell: false };
|
|
72
|
+
return { file: yad, args: [], shell: true };
|
|
73
|
+
}
|
|
74
|
+
const npx = onPath('npx');
|
|
75
|
+
if (npx) return { file: npx, args: ['--no-install', 'yadflow'], shell: IS_WINDOWS && /\.(cmd|bat)$/i.test(npx) };
|
|
76
|
+
return null;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// Run the resolved `yad` with `args` appended. `options` go to spawnSync.
|
|
80
|
+
function runYad(yad, args, options) {
|
|
81
|
+
const all = [...yad.args, ...args];
|
|
82
|
+
if (yad.shell) return spawnSync([yad.file, ...all].map(quoteForCmd).join(' '), { ...options, shell: true, windowsHide: true });
|
|
83
|
+
return spawnSync(yad.file, all, { ...options, windowsHide: true });
|
|
84
|
+
}
|
|
85
|
+
// ---- end yad-resolve ---------------------------------------------------------------------------------
|
|
86
|
+
|
|
87
|
+
// The payload is read here, so the protocol can be chosen even when `yad` cannot be reached.
|
|
88
|
+
let input = '';
|
|
89
|
+
try { input = process.stdin.isTTY ? '' : fs.readFileSync(0, 'utf8'); } catch { input = ''; }
|
|
90
|
+
let payload = null;
|
|
91
|
+
try { payload = JSON.parse(input); } catch { payload = null; }
|
|
92
|
+
const cursor = payload?.hook_event_name === 'beforeShellExecution' || typeof payload?.cursor_version === 'string';
|
|
93
|
+
const ALLOW = '{"permission":"allow"}';
|
|
94
|
+
const allow = (why) => {
|
|
95
|
+
if (why) process.stderr.write(` • yad hook: ${why} — allowing\n`);
|
|
96
|
+
if (cursor) process.stdout.write(`${ALLOW}\n`);
|
|
97
|
+
process.exit(0);
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
const yad = resolveYad();
|
|
101
|
+
if (!yad) allow(`no \`yad\` on PATH and none installed in ${PRODUCT_ROOT} (install yadflow to re-arm the agent guard)`);
|
|
102
|
+
|
|
103
|
+
const r = runYad(yad, ['hook', 'agent-guard', '--format', cursor ? 'cursor' : 'exit'], { input, stdio: ['pipe', 'pipe', 'inherit'], encoding: 'utf8' });
|
|
104
|
+
if (cursor) {
|
|
105
|
+
// The verdict is the last non-empty line that names a permission (see ledger-guard-cursor.mjs for why).
|
|
106
|
+
const lines = String(r.stdout || '').split(/\r?\n/).filter((l) => l.trim());
|
|
107
|
+
const verdict = lines.length ? lines[lines.length - 1] : '';
|
|
108
|
+
if (verdict.includes('"permission"')) { process.stdout.write(`${verdict}\n`); process.exit(0); }
|
|
109
|
+
allow(r.status === 0 ? '' : `\`yad hook agent-guard\` ${r.error ? r.error.message : `exited ${r.status ?? r.signal}`} (run \`yad doctor\` to check the install)`);
|
|
110
|
+
}
|
|
111
|
+
// Only an explicit deny (2) blocks: a yad that cannot run, or one older than this hook (it refuses the
|
|
112
|
+
// unknown action with another code), must not read as a refusal.
|
|
113
|
+
if (r.stdout) process.stdout.write(r.stdout);
|
|
114
|
+
if (r.status === 2) process.exit(2);
|
|
115
|
+
if (r.status !== 0) allow(`\`yad hook agent-guard\` ${r.error ? r.error.message : `exited ${r.status ?? r.signal}`} (run \`yad doctor\` to check the install)`);
|
|
116
|
+
process.exit(0);
|
|
@@ -77,9 +77,10 @@ the architecture gate. To also open the PR/MR in the same step, use `yad-ship`.
|
|
|
77
77
|
- **Trailer order is fixed:** `Task → Contract-Change → Ledger-Override → Co-Authored-By` (the override only
|
|
78
78
|
with `--manual`, the footer only when `--ai` is given).
|
|
79
79
|
- **Never widen the contract here.** A contract touch is flagged (`--contract-change`), not hidden.
|
|
80
|
-
- **Never pass `--manual`
|
|
81
|
-
|
|
82
|
-
reason must be one line.
|
|
80
|
+
- **Never pass `--manual` yourself, even when asked (E158).** Committing past the ledger hook is the person's
|
|
81
|
+
act. Give them the exact command (in Claude Code: `! yad commit --manual --reason "<why>"`), wait, then
|
|
82
|
+
confirm by reading (`git log -1`). `--manual` needs `--reason`, and the reason must be one line. The agent
|
|
83
|
+
guard hook refuses it if you try.
|
|
83
84
|
|
|
84
85
|
## Reference
|
|
85
86
|
- Branch/commit conventions + the file-boundary rule: `../yad-implement/references/implement-conventions.md`.
|
|
@@ -67,8 +67,11 @@ Determine which tool is being connected from `tool` (default `figma`); reject a
|
|
|
67
67
|
- **pencil** → the `pencil` MCP (`batch_design` writes `.pen` web/mobile screens — generate-capable).
|
|
68
68
|
- another adapter → its named MCP.
|
|
69
69
|
|
|
70
|
-
Record `provider` (the concrete MCP
|
|
71
|
-
|
|
70
|
+
Record `provider` (the concrete MCP) and whether it is available. For Figma, say which server it is,
|
|
71
|
+
because a UI task checks it before it starts (#358): `figma-desktop` (the Dev Mode MCP server inside the
|
|
72
|
+
running desktop app — the app must be open), `figma` (Figma's hosted server — a sign-in, no app), or
|
|
73
|
+
`html-to-design` (writes screens only, cannot read a frame). For Pencil, `pencil-mcp`. The older value
|
|
74
|
+
`figma-mcp` does not say which Figma server it is: on a refresh, record the exact one. **Auth is the local user's own** — the user's authenticated MCP session. The skill
|
|
72
75
|
**stores no tokens**; `project_url`/`files` are plain references, never credentials.
|
|
73
76
|
|
|
74
77
|
**Graceful degradation:** if no design-tool MCP is available, record `source: "unavailable"` and report
|
|
@@ -81,13 +84,13 @@ Upsert into `{project-root}/.sdlc/design.json` (create the file + parent `.sdlc/
|
|
|
81
84
|
```json
|
|
82
85
|
{
|
|
83
86
|
"tool": "figma",
|
|
84
|
-
"provider": "figma-
|
|
87
|
+
"provider": "figma-desktop",
|
|
85
88
|
"project_url": "https://www.figma.com/files/project/<id>/<name>",
|
|
86
89
|
"auth": "user",
|
|
87
90
|
"files": { "web": null, "mobile": null },
|
|
88
91
|
"connectedAt": "<YYYY-MM-DD>",
|
|
89
92
|
"lastSyncedAt": "<YYYY-MM-DD>",
|
|
90
|
-
"source": "figma-
|
|
93
|
+
"source": "figma-desktop"
|
|
91
94
|
}
|
|
92
95
|
```
|
|
93
96
|
|
|
@@ -56,6 +56,29 @@ it authors `ui-design.md` / `DESIGN.md` exactly as before and records `design: n
|
|
|
56
56
|
with a one-line note (mirroring the `impeccable: not-installed` degrade). No error — the design tool is
|
|
57
57
|
purely additive.
|
|
58
58
|
|
|
59
|
+
## Reachable before Build (#358)
|
|
60
|
+
|
|
61
|
+
A design tool read through its running desktop app — Pencil, or Figma's `figma-desktop` server — cannot be
|
|
62
|
+
read while the app is closed or the design file is not open. So before a UI task, `yad-spec` and
|
|
63
|
+
`yad-implement` check it first, and stop early when it fails. yad itself cannot call an MCP server (it
|
|
64
|
+
belongs to the agent's session), so `yad story frames <story> --json` returns a `preflight` block that says
|
|
65
|
+
how to check and what to tell the person; the text for each tool is the toolbox entry's `reach` field.
|
|
66
|
+
|
|
67
|
+
| `tool` | What the agent checks | When it fails |
|
|
68
|
+
|--------|-----------------------|---------------|
|
|
69
|
+
| `pencil` | `get_app_state` (or `get_editor_state`): the active canvas editor is the design file, compared by file name (the app shows the full path). A frame inside a container is not in the top-level list, so it is read by its ID before it counts as missing | open the Pencil desktop app with the file loaded, then continue |
|
|
70
|
+
| `figma`, provider `figma-desktop` | `get_metadata` on one recorded frame | open the Figma desktop app with the file loaded and its Dev Mode MCP server on |
|
|
71
|
+
| `figma`, provider `figma` (hosted) | `get_metadata` on one recorded frame | sign in to Figma in your agent; no app is needed |
|
|
72
|
+
| `figma`, provider `figma-mcp` (older value), any other name, or none | `get_metadata` on one recorded frame | either of the two above — yad cannot tell which server it is |
|
|
73
|
+
| `figma`, provider `html-to-design` | nothing: it writes screens and cannot read a frame | not checked; build from the frame links |
|
|
74
|
+
|
|
75
|
+
Also not checked (build from the frame links): no `design.json`, tool `none`, source `unavailable`; no
|
|
76
|
+
`design-links.json`, one that cannot be read, or one recorded for another tool (re-run the UI step); and a
|
|
77
|
+
story whose recorded frame IDs are all missing from `design-links.json` — the bad IDs are the problem then.
|
|
78
|
+
|
|
79
|
+
A failed check stops the step. The person may choose to go on from the frame links only; that choice is
|
|
80
|
+
recorded (in `spec.md`'s Clarifications, or the commit's Decisions paragraph).
|
|
81
|
+
|
|
59
82
|
## Staleness / refresh
|
|
60
83
|
|
|
61
84
|
A re-generated or designer-edited file is like a moved code repo: `yad-ui` **flags** a divergence and
|
|
@@ -15,13 +15,13 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
|
|
|
15
15
|
```json
|
|
16
16
|
{
|
|
17
17
|
"tool": "figma", // figma | pencil | <adapter id> | none (markdown-only)
|
|
18
|
-
"provider": "figma-
|
|
18
|
+
"provider": "figma-desktop", // the concrete MCP: figma-desktop | figma | html-to-design | pencil-mcp | null (figma-mcp: older, either Figma server)
|
|
19
19
|
"project_url": "https://www.figma.com/files/project/123/feature", // team/project/file reference; null if none yet
|
|
20
20
|
"auth": "user", // ALWAYS the user's own MCP session — never a token
|
|
21
21
|
"files": { "web": null, "mobile": null }, // optional default file refs per platform
|
|
22
22
|
"connectedAt": "2026-06-13", // first connect (YYYY-MM-DD)
|
|
23
23
|
"lastSyncedAt": "2026-06-13", // last connect/refresh
|
|
24
|
-
"source": "figma-
|
|
24
|
+
"source": "figma-desktop" // the MCP detected at connect | unavailable (degraded)
|
|
25
25
|
}
|
|
26
26
|
```
|
|
27
27
|
|
|
@@ -36,7 +36,7 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
|
|
|
36
36
|
session.
|
|
37
37
|
- **`connect` overwrites in place** — a project carries exactly one design connection at a time;
|
|
38
38
|
switching tools is just another `connect`. There is no array (unlike `repos.json`).
|
|
39
|
-
- **`source`** is the authority for availability: an MCP id (`figma-
|
|
39
|
+
- **`source`** is the authority for availability: an MCP id (`figma-desktop` / `figma` / `pencil-mcp` / …) means
|
|
40
40
|
`yad-ui` can generate/link; `unavailable` means `yad-ui` degrades to markdown-only. `refresh`
|
|
41
41
|
re-detects and may flip it.
|
|
42
42
|
- **`tool: "none"`** is a valid, deliberate state: a project that has chosen markdown-only. `yad-ui`
|
|
@@ -180,6 +180,14 @@ new repo later is the same `connect` action. Write no `domain_owner`/`domain_own
|
|
|
180
180
|
release wrote with them is left as it is (nothing reads them, and `yad doctor` warns
|
|
181
181
|
`people:domain-owners-unused`).
|
|
182
182
|
|
|
183
|
+
**Preview address (optional, #359).** A repo whose PRs/MRs get a live preview deployment (Vercel,
|
|
184
|
+
Netlify, a GitLab review app) can record its address pattern as `preview_url`, for example
|
|
185
|
+
`"https://pr-{pr}.myapp.dev"` (placeholders `{pr}`, `{branch}`, `{repo}`; https only, or
|
|
186
|
+
`http://localhost`). Ask the person for it; never guess one. Write it with
|
|
187
|
+
`yad repo preview <repo> <pattern>` (it checks the pattern; `--clear` removes it), not by hand. With no
|
|
188
|
+
pattern, review steps ask the platform for the PR's deployment, and else say the design check ran
|
|
189
|
+
locally only.
|
|
190
|
+
|
|
183
191
|
### Step 5 — Report
|
|
184
192
|
Report the connected repo, its `platform`, the pack + code-map paths, the secret-scan result, and that
|
|
185
193
|
the Shape phases will now load this repo's code-map. Nothing auto-advances; this is setup.
|
|
@@ -188,10 +196,11 @@ the Shape phases will now load this repo's code-map. Nothing auto-advances; this
|
|
|
188
196
|
|
|
189
197
|
- **`refresh`** — re-run Steps 2–4 (including Step 3b) for an already-connected repo (after its code moves). A new directory gets an `unset` line and a guess; a `confirmed` line is only ever suggested against. Updates
|
|
190
198
|
`syncedHead` + `lastSyncedAt`. Same machinery as `connect`. Once the AI has regenerated the
|
|
191
|
-
`code-map.md` (Step 3), publish it to the Product with **`yad repo refresh <repo> --push
|
|
199
|
+
`code-map.md` (Step 3), publish it to the Product with **`yad repo refresh <repo> --push`** — ask the
|
|
200
|
+
person first, every time: it pushes to the default branch (E158) — it
|
|
192
201
|
commits the tracked code-maps + `.sdlc/repos.json` (never the gitignored `pack.md`) as one
|
|
193
202
|
audit-trail commit `chore(product): sync code-context — <repos> by @<login> [skip ci]` and pushes it
|
|
194
|
-
straight to the Product's **default branch** (add `--allow-branch` to commit on a non-default branch).
|
|
203
|
+
straight to the Product's **default branch** (add `--allow-branch` to commit on a non-default branch, only when the person asks).
|
|
195
204
|
This is the code-context analogue of `yad checkpoint` — human-owned machine state, no Task trailer,
|
|
196
205
|
no Co-Authored-By.
|
|
197
206
|
- **`list`** — print every registry entry with a **fresh/stale** flag: compare each repo's current HEAD
|
|
@@ -253,7 +262,8 @@ any user name or password taken out of `git_url`) into every connected repo, and
|
|
|
253
262
|
to each repo's default branch — a record on disk that is not committed as it stands is committed by the
|
|
254
263
|
next `--push`, though `yad check` reads it as `ok`. The Product-reading gates read it from
|
|
255
264
|
the base; `checks/product-checkout.sh` uses it with the `YAD_PRODUCT_TOKEN` secret. After connecting a
|
|
256
|
-
repo, run `yad check --fix --
|
|
265
|
+
repo, run `yad check --fix --open-pr` (a PR/MR per repo, no asking), or `yad check --fix --push` after the
|
|
266
|
+
person says yes (it pushes to every repo's default branch, E158); `yad doctor` warns `repos:product-link-missing` until it is on
|
|
257
267
|
the repo's default branch.
|
|
258
268
|
|
|
259
269
|
## Live on-demand (the third context layer)
|
|
@@ -83,7 +83,8 @@ silently re-packing the whole repo. A phase never refreshes the registry on its
|
|
|
83
83
|
`yad repo refresh` (or `yad check --fix`). After the AI regenerates the code-map, `yad repo refresh
|
|
84
84
|
--push` publishes the refreshed code-maps + registry to the Product's default branch as a `chore(product): sync
|
|
85
85
|
code-context … [skip ci]` audit commit (never the pack's content; `--allow-branch` overrides the branch
|
|
86
|
-
guard
|
|
86
|
+
guard; it pushes to the default branch, so an AI agent asks the person first, every time, E158). The
|
|
87
|
+
`pack.md` is gitignored — `yad repo refresh`/`yad setup` scaffold
|
|
87
88
|
`.sdlc/code-context/*/pack.md` into the Product `.gitignore` (so a regenerated pack never dirties the tree),
|
|
88
89
|
and a Product that tracked the pack *before* that ignore existed is self-healed: `--push` untracks it and
|
|
89
90
|
lands the removal + the managed `.gitignore` line in the same audit commit. The commit is a scoped
|
|
@@ -54,7 +54,8 @@ not under any `epics/EP-<slug>/.sdlc/`.
|
|
|
54
54
|
Commit the **registry** (`repos.json`) and each repo's **`code-map.md`** — they are small, reviewable,
|
|
55
55
|
and are what the Shape phases actually read (a diff on a code-map shows when a repo's surface moved).
|
|
56
56
|
`yad repo refresh --push` commits and pushes exactly these (never `pack.md`) to the Product's default
|
|
57
|
-
branch as one `chore(product): sync code-context … [skip ci]` audit commit
|
|
57
|
+
branch as one `chore(product): sync code-context … [skip ci]` audit commit; an AI agent asks the person
|
|
58
|
+
before it, every time (E158).
|
|
58
59
|
**Ignore** the full Repomix `pack.md` — it is large and regenerable (`action: refresh`). The Product
|
|
59
60
|
's `.gitignore` carries `.sdlc/code-context/*/pack.md` for this. This mirrors how the per-epic
|
|
60
61
|
`.sdlc/` state (state.json, approvals.json, build-log.json) is committed.
|
|
@@ -56,8 +56,8 @@ auto-seeds epics. A product created before E75 may still hold the old spelling,
|
|
|
56
56
|
yad-run and the docs skills; `6-change` holds yad-change, yad-stub, yad-timeline, yad-defects and
|
|
57
57
|
yad-reconcile; yad-status (a read-only view) and yad-learn (a tutor for any stage) are `anytime`, the
|
|
58
58
|
value for a skill available at every stage — they are listed under
|
|
59
|
-
Automation below only because the site needs one place to draw them. yad-report
|
|
60
|
-
a CLI helper, not
|
|
59
|
+
Automation below only because the site needs one place to draw them. yad-report and yad-guide have no
|
|
60
|
+
phase: one is a CLI helper and the other the rules an AI agent follows, not pipeline steps.
|
|
61
61
|
Moving three of these from `1-front` needed no migration, and that does not contradict the note
|
|
62
62
|
above: module-help.csv is catalogue content the tool ships, read from the package's skills/sdlc/ folder
|
|
63
63
|
and never installed into a project. It is not state a user's project stores. The note above is about
|
|
@@ -59,6 +59,19 @@ asking questions, answering theirs, until both are satisfied — then records th
|
|
|
59
59
|
growth in the local-only learning log. Still soft: it rides the same `engagement: verified` signal and
|
|
60
60
|
never gates. When a pair session backs the approve, you may set `companion.pair: true` on the ship record.
|
|
61
61
|
|
|
62
|
+
**Live design check (a UI change only, #359).** A live design check opens the running page and looks
|
|
63
|
+
at it at several screen widths (phone, tablet, desktop). `yad review context --repo <r> --pr <n> --json`
|
|
64
|
+
carries a `preview` field that says where to run it:
|
|
65
|
+
- `preview.url` set (`source: pattern` from the repo's `yad repo preview` pattern, or `source: platform`
|
|
66
|
+
from the deployment GitHub/GitLab records for the PR): run the check against `preview.url`, and name it
|
|
67
|
+
in the review ("checked live on <url> at 375, 768 and 1280 px"). The address is where the preview
|
|
68
|
+
should be, not proof that it is there: if the page does not load, or does not show this PR's change
|
|
69
|
+
yet, treat it as `local-only` and say so.
|
|
70
|
+
- `source: local-only`: there is no preview deployment. Run the check on the developer's machine if you
|
|
71
|
+
can, and say plainly, in the review and in a PR comment, **"design check ran locally only: <preview.why>"**.
|
|
72
|
+
Never present a local check as a check of the deployed page. `preview.why` names the fix
|
|
73
|
+
(`yad repo preview <repo> <pattern>`); offer it, never run it unasked.
|
|
74
|
+
|
|
62
75
|
### Step 2 — `approve` (the engineer review — the human gate)
|
|
63
76
|
A human engineer reads the diff **against the spec** (`specs/<story>/`) and the acceptance criteria,
|
|
64
77
|
and records an approval. Determine the count with `bash checks/risk-route.sh <pr-body-file> origin/<base>`,
|
|
@@ -126,11 +139,13 @@ the gate talks only through files; refuse to treat AI review as a human approval
|
|
|
126
139
|
### Step 3 — `ship` (merge + record + update state)
|
|
127
140
|
Ship **iff ALL hold**: the check gates pass (Step C), the AI review has run (advisory), and the
|
|
128
141
|
engineer-review rule is satisfied (Step 2). Then:
|
|
129
|
-
- **Merge** the task branch into the repo's default branch
|
|
142
|
+
- **Merge** the task branch into the repo's default branch. The person merges it, never you, even when
|
|
143
|
+
your login could (E158): give them the PR/MR link, wait, then confirm by reading
|
|
144
|
+
(`yad build merged … --ship`).
|
|
130
145
|
- **Check the lane is not skipped (E39)** — read `build-state/<story>.json`. If this repo's lane is
|
|
131
|
-
`status: skipped`, it was set aside as needing no change: stop
|
|
132
|
-
`yad unskip <epic> <story> --repo <repo>` before recording a ship
|
|
133
|
-
things (`yad doctor` fails that as `lane:…:contradiction`; `yad checkpoint --retro-ship` refuses it).
|
|
146
|
+
`status: skipped`, it was set aside as needing no change: stop and tell the person. Only when they say
|
|
147
|
+
the lane is owed after all, run `yad unskip <epic> <story> --repo <repo>` before recording a ship
|
|
148
|
+
(E158), so the two records never say opposite things (`yad doctor` fails that as `lane:…:contradiction`; `yad checkpoint --retro-ship` refuses it).
|
|
134
149
|
- **See whether it merged — ask, do not wait (#355).** The merge is a person's, but you do not need them
|
|
135
150
|
to tell you it happened: run `yad build merged <story> --task <task> --repo <repo> --ship`. It asks the
|
|
136
151
|
platform about the task's PR/MR (found by its branch; `--pr <n>` names it) and answers one `state`
|
|
@@ -147,14 +162,16 @@ engineer-review rule is satisfied (Step 2). Then:
|
|
|
147
162
|
(`followUps`), never a second ship. Shape: `references/ship-and-record.md`.
|
|
148
163
|
- **Catch up on merges (#365)** — `yad build sync [<epic>]` records every ship the code repos already show
|
|
149
164
|
(what `yad reconcile check` finds merged with no ship), through `yad build ship`, then `yad build done`
|
|
150
|
-
for each story now fully shipped; it lists what it cannot record.
|
|
165
|
+
for each story now fully shipped; it lists what it cannot record. Then ask the person before
|
|
166
|
+
`yad checkpoint --push`: it pushes to the default branch, which is asked about every time (E158).
|
|
151
167
|
- **Record the ship** — `yad build ship <story> --task <task> --repo <repo> --pr <n>` (what `--ship` runs),
|
|
152
168
|
once the PR/MR has merged. A grouped PR (#350) — several small tasks of one story — ships each task it
|
|
153
169
|
carries from the same `--pr`; a task that is not the branch's is found with `--pr`, as its commits carry it. It reads the merge commit, the branch, the checks that passed, the approvers (with the
|
|
154
170
|
engagement signal), the body's `Risk level:` and the merge date from the platform, refuses a PR that is
|
|
155
171
|
not merged or that comes from another task's branch, and writes the ship to its own shard
|
|
156
172
|
`epics/<epic>/.sdlc/build-log/<story>-<task>-<repo>.json` (shape: `references/ship-and-record.md`). A
|
|
157
|
-
repo whose platform cannot be read records it by hand: `--merge-commit <sha> --approver <login
|
|
173
|
+
repo whose platform cannot be read records it by hand: `--merge-commit <sha> --approver <login>`, only with
|
|
174
|
+
the merge commit and approvers the person gave you, never guessed (E158). A
|
|
158
175
|
task merged with no PR/MR: `--merge-commit <sha>` and no `--pr` (the commit must be on the default
|
|
159
176
|
branch and name the task in its `Task:` trailer or subject; the platform is asked whether a PR merged it,
|
|
160
177
|
and a PR that did is named instead). It moves the story to `in-build`. Never write the shard by hand.
|
|
@@ -176,7 +193,8 @@ engineer-review rule is satisfied (Step 2). Then:
|
|
|
176
193
|
word on the trust signal: a diff merged as authored is `approved-unchanged`; one the engineer edited
|
|
177
194
|
before merge is `approved-with-edits`; a rejected one is `rejected`. This is the run record `yad dial`
|
|
178
195
|
shows the team beside a step's dial (it never weakens the merge gate — the engineer still owns the merge).
|
|
179
|
-
- **Commit the machine-written ledgers.**
|
|
196
|
+
- **Commit the machine-written ledgers.** Ask the person, then run `yad checkpoint --push` from `{project-root}`
|
|
197
|
+
(a push to the default branch is asked about every time, E158) to commit
|
|
180
198
|
the Build ledgers just written (the `build-log/` shard, and the `trust-log/` shard /
|
|
181
199
|
`build-state/<story>.json` if the story ran through `yad-run`) as one `chore(product): …` audit-trail
|
|
182
200
|
commit — default branch only, staging the shard dirs (`yad tidy up` folds finished shards later),
|