yadflow 4.6.0 → 4.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +259 -0
- package/README.md +46 -4
- package/bin/commands.mjs +9 -2
- package/bin/yad.mjs +309 -30
- package/cli/agent-guard.mjs +511 -0
- package/cli/agent-guide.mjs +83 -0
- package/cli/agent-rules.mjs +381 -0
- package/cli/argv-flags.mjs +7 -0
- package/cli/artifact-status.mjs +88 -20
- package/cli/build.mjs +1372 -0
- package/cli/checkpoint.mjs +2 -2
- package/cli/ci-check.mjs +492 -0
- package/cli/commit.mjs +1 -0
- package/cli/dial.mjs +21 -1
- package/cli/docs.mjs +7 -2
- package/cli/doctor.mjs +176 -33
- package/cli/epic-state.mjs +360 -12
- package/cli/errors.mjs +3 -0
- package/cli/find-product.mjs +36 -2
- package/cli/fold.mjs +9 -5
- package/cli/gate-local.mjs +9 -1
- package/cli/gate.mjs +364 -22
- package/cli/guide.mjs +549 -0
- package/cli/history.mjs +22 -2
- package/cli/hook.mjs +35 -4
- package/cli/index-command.mjs +2 -2
- package/cli/ledger.mjs +60 -0
- package/cli/lib.mjs +46 -0
- package/cli/lifecycle/defaults/2.json +124 -0
- package/cli/lifecycle/lifecycle.schema.json +5 -2
- package/cli/lifecycle.mjs +16 -3
- package/cli/manifest.mjs +75 -0
- package/cli/marked-block.mjs +48 -0
- package/cli/members.mjs +19 -5
- package/cli/migrate.mjs +17 -19
- package/cli/next.mjs +35 -12
- package/cli/openpr.mjs +81 -5
- package/cli/plan.mjs +326 -22
- package/cli/platform.mjs +21 -0
- package/cli/pr-list.mjs +5 -3
- package/cli/product-index.mjs +6 -3
- package/cli/product-token.mjs +186 -0
- package/cli/productcommit.mjs +33 -0
- package/cli/protection.mjs +50 -0
- package/cli/recommend.mjs +3 -1
- package/cli/reconcile.mjs +187 -26
- package/cli/repo-publish.mjs +2 -2
- package/cli/report.mjs +62 -14
- package/cli/run-checks.mjs +586 -0
- package/cli/setup.mjs +244 -25
- package/cli/ship-drift.mjs +49 -18
- package/cli/signing.mjs +377 -0
- package/cli/standup.mjs +1 -1
- package/cli/status.mjs +282 -0
- package/cli/test-agents-file.mjs +993 -0
- package/cli/test-build.mjs +1559 -0
- package/cli/test-ci-check.mjs +616 -0
- package/cli/test-guide.mjs +1267 -0
- package/cli/test-node.mjs +129 -0
- package/cli/test-run-checks.mjs +603 -0
- package/cli/test-setup-agent.mjs +352 -0
- package/cli/test-signing.mjs +524 -0
- package/cli/test-worktree.mjs +520 -0
- package/cli/thread.mjs +4 -0
- package/cli/tidy.mjs +2 -2
- package/cli/toolbox.mjs +37 -6
- package/cli/update-commit.mjs +313 -11
- package/cli/workspace.mjs +38 -10
- package/cli/worktree-record.mjs +53 -0
- package/cli/worktree.mjs +379 -0
- package/package.json +6 -4
- package/skills/sdlc/config.yaml +5 -5
- package/skills/sdlc/module-help.csv +2 -1
- package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
- package/skills/yad-change/SKILL.md +5 -1
- package/skills/yad-checks/SKILL.md +61 -12
- package/skills/yad-checks/references/check-gates.md +78 -14
- package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
- package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
- package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
- package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
- package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
- package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
- package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
- package/skills/yad-checks/templates/checks/package-manager.sh +42 -5
- package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
- package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
- package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
- package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
- package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
- package/skills/yad-checks/templates/github/yad-checks.yml +9 -9
- package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +4 -1
- package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +5 -5
- package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
- package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
- package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
- package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
- package/skills/yad-commit/SKILL.md +8 -5
- package/skills/yad-connect-repos/SKILL.md +5 -3
- package/skills/yad-connect-repos/references/code-context.md +2 -1
- package/skills/yad-connect-repos/references/repos-registry.md +2 -1
- package/skills/yad-docs/templates/app/package-lock.json +395 -106
- package/skills/yad-docs/templates/app/package.json +2 -2
- package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
- package/skills/yad-engineer-review/SKILL.md +55 -25
- package/skills/yad-engineer-review/references/ship-and-record.md +49 -12
- package/skills/yad-epic/SKILL.md +2 -1
- package/skills/yad-epic/references/state-schema.md +76 -17
- package/skills/yad-guide/SKILL.md +192 -0
- package/skills/yad-implement/SKILL.md +75 -13
- package/skills/yad-implement/references/implement-conventions.md +8 -1
- package/skills/yad-implement/templates/.gitmessage +3 -0
- package/skills/yad-open-pr/SKILL.md +21 -0
- package/skills/yad-pair-review/SKILL.md +14 -5
- package/skills/yad-pr-template/SKILL.md +6 -2
- package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
- package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
- package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
- package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
- package/skills/yad-product-bridge/SKILL.md +44 -12
- package/skills/yad-product-bridge/references/bridge.md +11 -5
- package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
- package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
- package/skills/yad-reconcile/SKILL.md +9 -3
- package/skills/yad-report/SKILL.md +15 -0
- package/skills/yad-review-companion/SKILL.md +5 -3
- package/skills/yad-review-gate/SKILL.md +16 -8
- package/skills/yad-review-gate/references/gating.md +26 -1
- package/skills/yad-run/SKILL.md +61 -33
- package/skills/yad-run/references/run-loop.md +44 -22
- package/skills/yad-spec/SKILL.md +137 -16
- package/skills/yad-spec/references/spec-handoff.md +50 -3
- package/skills/yad-status/SKILL.md +7 -0
- package/skills/yad-stories/references/story-schema.md +1 -1
- package/skills/yad-sync-repos/SKILL.md +2 -1
- package/skills/yad-ui/SKILL.md +2 -2
|
@@ -181,7 +181,7 @@ The engine writes everything this step used to spell out by hand (E42):
|
|
|
181
181
|
|
|
182
182
|
| The command says | Why | What to do |
|
|
183
183
|
|---|---|---|
|
|
184
|
-
| `<owner> skipped <step>` | a skip is a decision, not an artifact — carrying it would claim a review nobody did | leave that base out of `inherits`, then `yad skip` it on this epic
|
|
184
|
+
| `<owner> skipped <step>` | a skip is a decision, not an artifact — carrying it would claim a review nobody did | leave that base out of `inherits`, then, if it does not apply here either, offer to `yad skip` it on this epic: skipping is the person's decision, so run it only on their yes |
|
|
185
185
|
| `<owner> deferred <step>` | that work is still owed | leave the base out and author it on this epic, so the owed work follows the thread |
|
|
186
186
|
| `<owner> has not finished <step>` | nothing approved exists yet | finish it on the owner, or author it here |
|
|
187
187
|
| `holds no usable contract lock` / `surface no longer matches its lock` | you may skip authoring a contract, never having one | lock (or re-lock) the owner's surface first (`yad-architecture` Step 5) |
|
|
@@ -257,6 +257,10 @@ again. Unbound, that command names `yad-architecture` for a contract-surface cha
|
|
|
257
257
|
## Hard rules
|
|
258
258
|
|
|
259
259
|
- **Never mutate a locked artifact.** A change is a new threaded epic, not an edit to a shipped one.
|
|
260
|
+
The one exception is BEFORE Build begins — no story has a Build lane and nothing has shipped: then
|
|
261
|
+
the person reopens the approved step with `yad gate reopen <epic> <step> --reason "<why>"` (#322; theirs
|
|
262
|
+
to run, E158: give them the command, then confirm with `yad gate status <epic>`) instead of
|
|
263
|
+
threading a change epic; every gate from that step is approved again.
|
|
260
264
|
- **A change MUST thread to a real parent.** Validate the parent + thread first; STOP on a broken lineage.
|
|
261
265
|
- **Inherit by reference, never copy.** `yad epic new --parent` carries inherited steps as `satisfied` with
|
|
262
266
|
`inherited: true` + a `boundHash`; the pointer-lock carries the owner's hash verbatim. The gate never
|
|
@@ -35,9 +35,11 @@ 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
|
+
A missing token on a PR that is not from a fork is a `WARNING` in CI, and a token that expires within
|
|
42
|
+
30 days is warned about there too (#345); `yad doctor` reports where each code repo's CI gets it.
|
|
41
43
|
3. **build/test/lint** — standard quality stage; tests must actually exercise new behavior, not just pass.
|
|
42
44
|
CI installs and runs through the package manager declared by the repo's standard
|
|
43
45
|
`package.json#packageManager` field (`npm` and `pnpm` are supported; any other manager stays on
|
|
@@ -80,7 +82,7 @@ from CI. `product-repo` is read from the base, a Product this repo tracks is rea
|
|
|
80
82
|
`epic:` must be the story ID's prefix — the PR cannot choose what is gated (E117, E118). See `references/check-gates.md` and `skills/yad-change`.
|
|
81
83
|
|
|
82
84
|
The gates are **CI-agnostic bash** in `checks/`; thin pipeline configs invoke them on GitHub Actions
|
|
83
|
-
and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the skill or let CI run them;
|
|
85
|
+
and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the skill (`yad run checks`) or let CI run them;
|
|
84
86
|
**nothing auto-advances**. The gates are blocking in CI (all but the advisory risk-map check), but the human still owns the merge (Step E).
|
|
85
87
|
|
|
86
88
|
## Conventions
|
|
@@ -116,6 +118,16 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
|
|
|
116
118
|
`templates/hooks/ledger-guard-cursor.mjs` and a `preToolUse` entry in `.cursor/hooks.json`.
|
|
117
119
|
Fails OPEN; see "Step 2b" below. Every hook is a Node script the entry runs as `node <script>`, so
|
|
118
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.
|
|
119
131
|
- `templates/hooks/yad-capture.mjs` → **Product-only**, in **both** ledger modes (E43): the post-edit
|
|
120
132
|
harness hook that runs `yad capture --hook`, which snapshots every changed Shape artifact onto the
|
|
121
133
|
person's private `yad/wip/<name>/<epic>` branches without touching the checkout. Wired as a
|
|
@@ -191,20 +203,50 @@ Copy from this skill's `templates/`:
|
|
|
191
203
|
human to paste (graceful degradation — never guess-edit a pipeline you cannot parse).
|
|
192
204
|
- The legacy standalone `templates/gitlab/.gitlab-ci.yml` is retained only for a clean greenfield repo
|
|
193
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.
|
|
194
211
|
- **Tag-locked runners** (`run_untagged: false`, common on self-hosted): the fragment's jobs run a
|
|
195
|
-
docker image, so set a `YAD_RUNNER_TAGS` CI/CD variable (e.g. `dind_runner`) to route them —
|
|
196
|
-
|
|
212
|
+
docker image, so set a `YAD_RUNNER_TAGS` CI/CD variable (e.g. `dind_runner`) to route them — every
|
|
213
|
+
GitLab fragment's jobs carry `tags: [$YAD_RUNNER_TAGS]`. When unset, current GitLab (≥15) drops the
|
|
197
214
|
empty-expanded tag so the jobs run untagged (gitlab.com shared runners); older versions may
|
|
198
215
|
strand them `pending`, in which case set the variable to a real tag. The variable lives in
|
|
199
216
|
project settings, so it survives every `yad` sync. Single value only — `tags: [$VAR]` is one tag
|
|
200
|
-
equal to the whole variable, not a comma-split.
|
|
217
|
+
equal to the whole variable, not a comma-split. Leave **Protect variable** unticked on both
|
|
218
|
+
variables below: a protected variable reaches only pipelines on protected branches, so the MR
|
|
219
|
+
gates would run without it — untagged and on the default Node line.
|
|
220
|
+
- **The Node line** (#364): every GitLab job runs `image: node:${YAD_NODE_VERSION}`, `22` by default.
|
|
221
|
+
Set a `YAD_NODE_VERSION` CI/CD variable (a current `20`, `22` or `24` line) to change it — a
|
|
222
|
+
project variable wins over the fragment's value, so the fragment itself is never edited.
|
|
223
|
+
- **Shell-executor runners** ignore `image:`. The jobs then run on the runner host as they are, so
|
|
224
|
+
the host needs `bash`, `git`, `curl` (the signature gates read the GitLab API with it; without it
|
|
225
|
+
every commit reads as unverified) and Node (any current 22 or 24 line — for example from nvm)
|
|
226
|
+
on the runner user's `PATH`, plus whatever the repo's own build needs (Corepack, pnpm, …) for
|
|
227
|
+
`build-test-lint`. `YAD_NODE_VERSION` has no effect there. Point `YAD_RUNNER_TAGS` at that
|
|
228
|
+
runner's tag.
|
|
229
|
+
- **Do not hand-edit the fragments to fit a runner.** They are managed bytes: `yad check` reports a
|
|
230
|
+
hand-edited one as `modified`, and a plain `yad update` leaves it alone — so it never receives a
|
|
231
|
+
fix again. Both runner settings above are CI/CD variables, so no edit is needed: move the
|
|
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
|
|
234
|
+
a `.yad-orig` copy of the edited one first). `yad doctor` warns when a wired
|
|
235
|
+
fragment has no `tags:` (`YAD-CI-001`) or still runs a fixed `node:<n>` image (`YAD-CI-002`, an
|
|
236
|
+
install from before the variable — `yad update` replaces it).
|
|
237
|
+
- **Product jobs of your own** (`yad-product-checks.yml`): before #364 this fragment set its image
|
|
238
|
+
and tag in a top-level `default:`, which GitLab applies to every job in the pipeline — the
|
|
239
|
+
Product's own jobs too. They now sit on the yad jobs only. A job of yours that had no `image:` or
|
|
240
|
+
`tags:` and relied on that block needs its own after `yad update`.
|
|
201
241
|
|
|
202
242
|
- Ensure `<repo>/package.json` defines `lint`, `build`, `test` scripts (see `references/check-gates.md`
|
|
203
243
|
for the canonical scripts). **Only ADD a missing script; never overwrite an existing one.**
|
|
204
244
|
|
|
205
245
|
Re-running `wire` is **idempotent** — markers (`# yad-managed: yad-checks`,
|
|
206
246
|
`# yad-managed-include: yad-checks`) and the include-entry check make a second run a no-op.
|
|
207
|
-
|
|
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).
|
|
208
250
|
|
|
209
251
|
**The Product is wired the same way.** `repo: product` wires the Product repo itself (platform from `.sdlc/product.json`)
|
|
210
252
|
with a Product-flavored gate set — see "Wiring the Product" in `references/check-gates.md`.
|
|
@@ -212,7 +254,9 @@ with a Product-flavored gate set — see "Wiring the Product" in `references/che
|
|
|
212
254
|
**The Product also gets the agent guardrail** (see below): `templates/hooks/ledger-guard.mjs` →
|
|
213
255
|
`<product>/hooks/ledger-guard.mjs`, plus the `PreToolUse` entry in `.claude/settings.json`. A project
|
|
214
256
|
whose targets include `.cursor` also gets `templates/hooks/ledger-guard-cursor.mjs` and a `preToolUse`
|
|
215
|
-
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.
|
|
216
260
|
|
|
217
261
|
### Step 2b — the agent guardrail (harness hooks, verified mode only)
|
|
218
262
|
The CI gates speak at CI time. That is too late for one failure the field kept hitting (#171): in
|
|
@@ -248,9 +292,9 @@ file-editing tool call and refuses the write up front, naming the command that o
|
|
|
248
292
|
- **A no-op with a local ledger.** There the ledger is locally owned and the hand-edit the authoring
|
|
249
293
|
skills describe is *correct*, so nothing is wired and nothing is blocked.
|
|
250
294
|
- **It fails OPEN** — no `yad`, no Product, an unreadable config, an unparseable payload all ALLOW, with
|
|
251
|
-
a note on stderr. `ledger-guard` in CI fails *closed* and remains the authority.
|
|
252
|
-
|
|
253
|
-
"<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).
|
|
254
298
|
- **Known gaps** (both caught by the CI gate instead): a `Bash` tool call (`sed -i epics/…`) is not
|
|
255
299
|
intercepted — matching it would mean parsing shell; and the hook arms sessions **rooted at the
|
|
256
300
|
Product**, since a harness reads hooks from its own project root — a session opened at the workspace
|
|
@@ -270,7 +314,12 @@ it. Branch protection is what makes the CI gates hold a merge at all: point the
|
|
|
270
314
|
`docs/branch-protection.md`.
|
|
271
315
|
|
|
272
316
|
### Step 3 — `run` (run the gates now)
|
|
273
|
-
From inside the repo, run
|
|
317
|
+
From inside the repo, run `yad run checks` (add `--body <file>` holding the PR/MR description, and
|
|
318
|
+
`--title` unless the branch has exactly one commit). It runs every installed gate as CI does — the
|
|
319
|
+
Product's default branch where CI checks it out, every gate even after one fails — and prints a summary;
|
|
320
|
+
report PASS, FAIL or skipped per gate from it (`--json` lists each gate's FAIL lines). A skipped
|
|
321
|
+
pr-title or pr-template is not a pass. It runs `npm ci` (which replaces `node_modules`) and the build;
|
|
322
|
+
add `--no-build` when that is not wanted. One gate by hand:
|
|
274
323
|
```
|
|
275
324
|
bash checks/spec-link.sh "<base>"
|
|
276
325
|
bash checks/contract-check.sh "<base>"
|
|
@@ -4,6 +4,9 @@ The gates are the production-safety core of Build (Phase 3 build plan §C). They
|
|
|
4
4
|
deliberately small, separate, and CI-agnostic: plain bash in `checks/`, invoked by whatever CI the
|
|
5
5
|
repo uses. Each reads conventions established by earlier steps — it invents nothing.
|
|
6
6
|
|
|
7
|
+
For people, `docs/GATES.md` in the yadflow repo lists every gate's rules, exemptions and failure
|
|
8
|
+
messages, with what to change for each. When a gate's rule or message changes, update that page too.
|
|
9
|
+
|
|
7
10
|
## What each gate reads (the convention map)
|
|
8
11
|
|
|
9
12
|
| Gate | Reads | Source step |
|
|
@@ -75,6 +78,18 @@ Every gate stops on its failure except **risk-map**, which is advisory: there a
|
|
|
75
78
|
A maintenance commit that *does* carry a `Task:` trailer is resolved like any other: a malformed id
|
|
76
79
|
or a missing `specs/<story>/link.md` **FAILS**. Otherwise the trailer is decorative on exempt
|
|
77
80
|
commits and an unlinked `chore:` is indistinguishable from one naming a story that never existed.
|
|
81
|
+
- **SHA exemption** (shared with lineage-check, epic-open and reconcile-debt — one byte-identical block).
|
|
82
|
+
A commit listed in `.sdlc/gate-exempt` (or `SDLC_GATE_EXEMPT`; one full hex SHA per line — 40
|
|
83
|
+
characters, 64 in a SHA-256 repo, `#` comments; a short SHA is refused, as a tag of that name would stand in for it) **PASSes** before anything else is judged,
|
|
84
|
+
so it skips every check of the four gates, not only the trailer's. `SDLC_GATE_EXEMPT` comes from the
|
|
85
|
+
pipeline config, which a PR may edit; it still names a file on the base, so it cannot list the PR's
|
|
86
|
+
own commits, and guarding the pipeline itself is branch protection's job. It is for history already on a shared
|
|
87
|
+
branch whose trailer cannot be reworded — otherwise every later range that holds it, a release PR
|
|
88
|
+
above all, fails again. The list is read **from the base**, never from the PR, so a PR cannot waive
|
|
89
|
+
its own commits. An entry exempts nothing, and is said as a note, when it is a branch or tag name, a
|
|
90
|
+
short SHA, a SHA of the wrong length for this repo (64 characters in a SHA-1 repo, 40 in a SHA-256
|
|
91
|
+
one — git would look it up as a ref name), an annotated tag's or a tree's SHA, or a SHA that names no
|
|
92
|
+
object here.
|
|
78
93
|
- For every other commit, requires a `Task: <story>-<task>` trailer. **FAIL** if absent.
|
|
79
94
|
- The trailer must be a well-formed `<story>-T<NN>` id. **FAIL** on a malformed trailer (e.g.
|
|
80
95
|
`EP-demo-S01` with no `-T<NN>`) rather than letting it slip through the suffix-strip.
|
|
@@ -257,7 +272,7 @@ Every gate stops on its failure except **risk-map**, which is advisory: there a
|
|
|
257
272
|
pinned Node. A declared `packageManager` needs
|
|
258
273
|
Corepack, which ships with Node 18 through 24 (Node 25+ dropped it) and, before 18.20.7 / 20.19 /
|
|
259
274
|
22.14, carries registry keys too old to verify anything published since 2025 — so the override
|
|
260
|
-
should stay on a current
|
|
275
|
+
should stay on a current 22 or 24 line (or install a current Corepack first). The installer
|
|
261
276
|
checks for the binary and wraps `corepack prepare`, so both an absent and a stale Corepack fail
|
|
262
277
|
with that guidance instead of a bare "command not found" or "Cannot find matching keyid".
|
|
263
278
|
- Tests must actually exercise behavior (build plan §C) — an empty or trivially-passing suite does not
|
|
@@ -360,7 +375,9 @@ from the event payload):
|
|
|
360
375
|
pass — it has no EP artifact to review.
|
|
361
376
|
- **Anti-bypass guard.** The branch name alone is not trusted: a non-review head that actually
|
|
362
377
|
changes Shape artifacts (any path under `epics/**` or `foundation/**`) **FAILS** — those changes must go through
|
|
363
|
-
a `review/EP-*` PR and the artifact-review workflow.
|
|
378
|
+
a `review/EP-*` PR and the artifact-review workflow. The message says how: move them to a
|
|
379
|
+
`review/<epic>/<artifact>` branch (`review/EP-foundation/foundation` for the Foundation) and run
|
|
380
|
+
`yad open-pr` from it, or drop them from the PR. CI passes the PR's changed paths via
|
|
364
381
|
`--changed <file>` (computed from the diff against the base ref); without that list (a direct
|
|
365
382
|
by-hand caller) the guard is inert and the branch split alone applies. A step owner file
|
|
366
383
|
(`epics/<epic>/.sdlc/owners/<step>.json`, `foundation/.sdlc/owners/…`, written by `yad assign`,
|
|
@@ -384,18 +401,36 @@ catches a free-form description that bypassed it:
|
|
|
384
401
|
`## Impact & Risk`, `## Checklist`, filled `Risk level:`).
|
|
385
402
|
- **Anti-bypass guard** (same as pr-title): a non-review head that changes Shape artifacts
|
|
386
403
|
(`epics/**` or `foundation/**`, detected from the CI-supplied `--changed <file>` list) **FAILS** — artifact changes
|
|
387
|
-
must go through a `review/EP-*` PR. Step owner files alone do not count (E47).
|
|
404
|
+
must go through a `review/EP-*` PR, and the message says how, as in pr-title. Step owner files alone do not count (E47).
|
|
388
405
|
|
|
389
406
|
**GitLab truncates the description this gate reads.** `$CI_MERGE_REQUEST_DESCRIPTION` stops at **2700
|
|
390
407
|
characters**, so a long but perfectly valid MR can lose a required section *before the gate sees it* —
|
|
391
408
|
the author then reads "does not use the template" while looking at a description that visibly contains
|
|
392
|
-
it (#164). GitHub is unaffected (`github.event.pull_request.body` is not truncated).
|
|
393
|
-
|
|
409
|
+
it (#164). GitHub is unaffected (`github.event.pull_request.body` is not truncated). Three mitigations,
|
|
410
|
+
all shipped:
|
|
411
|
+
|
|
412
|
+
- **the gate reads the whole description (#343).** In GitLab CI, when GitLab says it cut the description
|
|
413
|
+
(`CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED`) or the text it was handed has reached 2700 characters, the
|
|
414
|
+
gate reads it again in full from the merge request API
|
|
415
|
+
(`$CI_API_V4_URL/projects/$CI_MERGE_REQUEST_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID`) and checks
|
|
416
|
+
that instead. The token is the `GITLAB_TOKEN` (or `SDLC_API_TOKEN`) CI/CD variable — the same
|
|
417
|
+
`read_api` token `yad-verified-commits` already needs — or, without one, the job's own `CI_JOB_TOKEN`,
|
|
418
|
+
which GitLab's job-token access list allows on a single merge request (an older GitLab may not). It goes to `curl` in a header file, never on
|
|
419
|
+
its command line, and only to that GitLab's own API; `node` decodes the answer. If the full text
|
|
420
|
+
cannot be read (no token that works, no `curl` or `node`, no answer), the cut body is checked as
|
|
421
|
+
before and the note below also says why and to set `GITLAB_TOKEN`. A fork's pipeline runs in the fork
|
|
422
|
+
and cannot read the target project's merge request; its note says so, and only the order of the
|
|
423
|
+
sections helps there. The API answers with the description as it is now, so a job re-run after the
|
|
424
|
+
author edits a long description checks the edit (a short one is read from the pipeline's variable);
|
|
394
425
|
|
|
395
426
|
- the GitLab MR templates (`yad-pr-template` `templates/gitlab/…` and `templates/product/gitlab/…`) carry
|
|
396
427
|
the constraint as a comment and keep every required section early, so a truncated body still passes;
|
|
397
|
-
- when a required section is missing **and** the body it read
|
|
398
|
-
|
|
428
|
+
- when a required section is missing **and** the body it read was cut (GitLab's flag, or ≥ 2700
|
|
429
|
+
characters) and the full text could not be read, the gate prints a `NOTE` naming the truncation, why
|
|
430
|
+
the full text was not read and, only where a token change can help, what to change (no variable and a
|
|
431
|
+
refusal: set `GITLAB_TOKEN`, or in a fork, that a fork cannot read the target's MR; a variable that is
|
|
432
|
+
set: 401 renew or replace it, 403 give it `read_api`, 404 its user cannot see the project; a timeout, a
|
|
433
|
+
5xx or an odd answer: the reason alone), and the fix — reorder the required sections above the cutoff and push
|
|
399
434
|
the long narrative to the end. Never delete a section: reordering is always allowed.
|
|
400
435
|
|
|
401
436
|
## 8. Phase 6 — feature-thread gates (`lineage-check.sh`, `epic-open.sh`, `reconcile-debt-check.sh`)
|
|
@@ -406,7 +441,10 @@ resolve the owning epic the same way: `Task:` trailer → `specs/<story>/link.md
|
|
|
406
441
|
→ the Product epic. All **fail closed** on an unresolvable base; all are **per commit**; `ci|chore|build|test`
|
|
407
442
|
commits **with no `Task:` trailer** are exempt — like spec-link, the exemption waives the requirement
|
|
408
443
|
for an owning epic, never the validity of one that is claimed, so a maintenance subject cannot buy a
|
|
409
|
-
pass past the sealed-epic / orphan-thread / frozen-thread checks.
|
|
444
|
+
pass past the sealed-epic / orphan-thread / frozen-thread checks. The one deliberate exception is the
|
|
445
|
+
SHA exemption (§1): a commit listed in the base's `.sdlc/gate-exempt` skips all three gates, those checks
|
|
446
|
+
included, before anything else is judged — a reviewed waiver of one named commit, which no subject line
|
|
447
|
+
can buy. When the **Product is not reachable** from CI (the usual case for a code-repo
|
|
410
448
|
PR), each degrades to a **PASS-with-note** — the Product-side check (`yad doctor` / `yad reconcile`) covers
|
|
411
449
|
that path, and spec-link still proves the story link.
|
|
412
450
|
|
|
@@ -664,11 +702,15 @@ workflows run `checks/product-checkout.sh` (wired into every code repo). It read
|
|
|
664
702
|
`YAD_PRODUCT_TOKEN` secret is set, clones the Product's `default_branch` (depth 1; the remote's own default when the record names
|
|
665
703
|
none) into the record's `path`. To turn it on:
|
|
666
704
|
|
|
667
|
-
1. From the Product, run `yad check --fix --
|
|
668
|
-
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
|
|
669
708
|
`.sdlc/product.json` first (`yad setup` fills it from the `origin` remote). On a Product that has only
|
|
670
709
|
`.sdlc/hub.json`, set it there, and never create a `product.json` beside it by hand; when both exist,
|
|
671
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
|
+
|
|
672
714
|
2. Make a token that can **read** the Product repository — on GitHub a fine-grained personal access
|
|
673
715
|
token or a GitHub App token with `contents: read` on that one repo (the workflow's own `GITHUB_TOKEN`
|
|
674
716
|
cannot read another private repo); on GitLab a project or group access token with `read_repository`.
|
|
@@ -686,10 +728,13 @@ What it does in each case:
|
|
|
686
728
|
|
|
687
729
|
| Case | Result |
|
|
688
730
|
| --- | --- |
|
|
689
|
-
| No record on the base, no `
|
|
690
|
-
|
|
|
731
|
+
| No record on the base, no `git_url` in the record (or one written with a JSON escape, a quote or a backslash, which it cannot read: write it without escapes), or no `YAD_PRODUCT_TOKEN` on a PR from a fork (a fork is never given secrets) or outside CI | A note; nothing is cloned, and the gates defer as before. |
|
|
732
|
+
| No `YAD_PRODUCT_TOKEN` on a PR/MR that is **not** from a fork, while the base record names the Product (#345) | A `WARNING [product-checkout]` line (and a `::warning` annotation on GitHub); nothing is cloned and the gates defer — the job does not fail. On GitHub the workflow passes `YAD_PR_FORK` (head repo ≠ this repo); on GitLab the pipeline is a fork's when it runs outside the MR's target project (`CI_PROJECT_ID` ≠ `CI_MERGE_REQUEST_PROJECT_ID`) — a fork's MR pipeline a maintainer runs in the target project gets its variables, and warns. A Dependabot PR is told to add the token as a Dependabot secret too. |
|
|
733
|
+
| A token whose expiry the Product host reports within 30 days (#345) | A `WARNING` naming the date; the clone goes on. More than 30 days: a note with the date. |
|
|
734
|
+
| The host rejects the token on its API (HTTP 401) | If the clone then fails: **FAIL**, saying the token has expired or been revoked. If the clone works: a `WARNING`. |
|
|
735
|
+
| The record's `path` is outside the repo, `.`, absolute, or under `.git` | **FAIL** — CI can only check a second repo out inside the workspace. Change `path` in its own PR and merge that first (the record is read from the base; `yad check --fix` keeps a `path` that is set). An empty `path` is one `yad check --fix --push` from the Product writes, for each code repo cloned on that machine on its default branch. A path of only spaces fails too, and so does one written with a JSON escape, a quote or a backslash, which the gate cannot read: change that one. |
|
|
691
736
|
| A folder on the way to `path` is a symlink (one the PR tracks, say) | **FAIL** — git would clone through it, to wherever it points. |
|
|
692
|
-
| The `path` holds files this repo tracks | **FAIL** — the gates refuse a tracked Product path anyway. |
|
|
737
|
+
| The `path` holds files this repo tracks | **FAIL** — the gates refuse a tracked Product path anyway. Untrack the files if they do not belong in the repo (`git rm -r --cached --`, and add the folder to `.gitignore`), or change `path` in its own PR and merge that first. |
|
|
693
738
|
| The folder is already there | Left as it is. |
|
|
694
739
|
| The clone fails with a token set | **FAIL**, naming the URL and branch — a broken setup must not read like a deferral. |
|
|
695
740
|
|
|
@@ -697,6 +742,18 @@ The token is handed to git through its environment (`GIT_CONFIG_COUNT`, git 2.31
|
|
|
697
742
|
never on a command line or in a URL; on GitHub the encoded form is masked too. An `ssh` `git_url`
|
|
698
743
|
(`git@host:org/repo.git`) is cloned as the same repo over `https`.
|
|
699
744
|
|
|
745
|
+
**The token's expiry (#345).** Before the clone, the script makes one call to the Product host's API with
|
|
746
|
+
the token, handed to `curl` in a header file (`-H @file`), never on its command line, and only to the
|
|
747
|
+
Product's own host — or, for GitHub's cloud, its API host (`api.github.com`, `api.<sub>.ghe.com`). The API is chosen by that host first — `github.com` and `*.ghe.com` are GitHub, a host
|
|
748
|
+
with `gitlab` in its name is GitLab — and only for any other host by the CI it runs in. GitHub:
|
|
749
|
+
`rate_limit`, whose `github-authentication-token-expiration` response header carries a personal access
|
|
750
|
+
token's expiry. GitLab: `/api/v4/personal_access_tokens/self`, whose `expires_at` is the token's. A
|
|
751
|
+
token with only `read_repository` — the least it needs to clone — may not call GitLab's API at all
|
|
752
|
+
(HTTP 403); the note then points at `yad doctor`, which warns about the Product's **project** access
|
|
753
|
+
tokens that expire soon (not group or personal ones). A token with no expiry, an app token or no `curl` gives a note too, never a failure — only the clone
|
|
754
|
+
decides that. `yad doctor` checks where the token is SET (see
|
|
755
|
+
`docs/CLI.md`); it never sees the token itself.
|
|
756
|
+
|
|
700
757
|
## Sync with existing CI (merge, never clobber)
|
|
701
758
|
|
|
702
759
|
`wire` is **additive**: it brings the SDLC gates into a repo that may already have CI, without ever
|
|
@@ -894,7 +951,8 @@ logic is unit-tested (`cli/hook.mjs`, `cli/test.mjs`; the scripts in `cli/test-h
|
|
|
894
951
|
an unreadable `product.json` / `hub.json`, an unparseable payload, a `yad` that errors — every one of them ALLOWS,
|
|
895
952
|
with a note on stderr. A local guardrail that failed closed would brick an agent's ability to edit
|
|
896
953
|
anything the moment an install went sideways. The CI gate fails **closed** and is what actually
|
|
897
|
-
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).
|
|
898
956
|
The door for a PERSON is `yad commit --manual --reason "<why>"` (E49): it skips the local hook for that
|
|
899
957
|
one commit and records the reason as a `Ledger-Override:` trailer. `ledger-guard` in CI still FAILS the
|
|
900
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
|
|
@@ -956,6 +1014,12 @@ names can actually close:
|
|
|
956
1014
|
|
|
957
1015
|
## Running by hand (Phase 3 is manual)
|
|
958
1016
|
|
|
1017
|
+
`yad run checks` runs every installed gate in one go, the way CI runs them: this repo's own `checks/`,
|
|
1018
|
+
against `origin/<default branch>`, with the Product's default branch written where
|
|
1019
|
+
`.sdlc/product-link.json` says while the four Product-reading gates run, and removed after (a folder
|
|
1020
|
+
already there is read as it is and kept: a run removes only what it wrote). Signatures are checked with git there; the platform's
|
|
1021
|
+
Verified badge is judged in CI. To run one gate on its own:
|
|
1022
|
+
|
|
959
1023
|
From inside the code repo, against the PR/MR base (e.g. `master`). For the gates that take one, the
|
|
960
1024
|
base argument is optional — omit it and the gate resolves the trunk in the order above (configured
|
|
961
1025
|
`default_branch`, else `origin/HEAD`, else `origin/main`), printing the base it chose; pass it (or
|
|
@@ -18,10 +18,29 @@ package_manager="$(yad_detect_package_manager "$package_manager_spec")"
|
|
|
18
18
|
run_with_words="$(yad_package_manager_command "$package_manager_spec" "$package_manager")"
|
|
19
19
|
read -r -a run_with <<< "$run_with_words"
|
|
20
20
|
|
|
21
|
+
# One step of the gate. A failing step used to end the job under `set -e` with only the tool's own
|
|
22
|
+
# output; this names the step, the command to run by hand, and the missing-script case (#351).
|
|
23
|
+
run_step() {
|
|
24
|
+
local step="$1" has=0
|
|
25
|
+
shift
|
|
26
|
+
# Checked before it runs: npm prints nothing for a missing script, and runs an empty one as a pass,
|
|
27
|
+
# so an empty "test" would read as green. Exit 3 is "none"; a package.json node cannot read is left
|
|
28
|
+
# to the run itself, which reports it.
|
|
29
|
+
YAD_STEP="$step" node --input-type=module -e 'import fs from "node:fs"; const p=JSON.parse(fs.readFileSync("package.json", "utf8").replace(/^\uFEFF/, "")); const s=p.scripts?.[process.env.YAD_STEP]; process.exit(typeof s === "string" && s.trim() ? 0 : 3)' 2>/dev/null || has=$?
|
|
30
|
+
if [ "$has" = 3 ]; then
|
|
31
|
+
echo "FAIL [build/test/lint]: package.json has no \"${step}\" script, or an empty one — add one; the gate runs lint, build and test, in that order."
|
|
32
|
+
exit 1
|
|
33
|
+
fi
|
|
34
|
+
if ! "${run_with[@]}" run --silent "$step" "$@"; then
|
|
35
|
+
echo "FAIL [build/test/lint]: '${run_with_words} run ${step}' failed — the output above says why. Run it on your machine, fix what it reports, and push again."
|
|
36
|
+
exit 1
|
|
37
|
+
fi
|
|
38
|
+
}
|
|
39
|
+
|
|
21
40
|
echo "[build/test/lint] lint…"
|
|
22
|
-
|
|
41
|
+
run_step lint
|
|
23
42
|
echo "[build/test/lint] build…"
|
|
24
|
-
|
|
43
|
+
run_step build
|
|
25
44
|
|
|
26
45
|
# Worker cap: when YAD_TEST_MAX_WORKERS is set AND the repo's test script is jest/vitest (the
|
|
27
46
|
# runners that accept --maxWorkers), forward it to bound CI test concurrency. For any other runner
|
|
@@ -39,6 +58,6 @@ fi
|
|
|
39
58
|
echo "[build/test/lint] test…"
|
|
40
59
|
# Intentional word-splitting: $extra is empty, `-- --maxWorkers=N` (npm), or `--maxWorkers=N` (pnpm).
|
|
41
60
|
# shellcheck disable=SC2086
|
|
42
|
-
|
|
61
|
+
run_step test $extra
|
|
43
62
|
|
|
44
63
|
echo "PASS [build/test/lint]: lint, build, and tests all green."
|
|
@@ -31,7 +31,7 @@ product_config() {
|
|
|
31
31
|
if [ -n "${SDLC_PRODUCT_CONFIG:-}" ]; then printf '%s' "$SDLC_PRODUCT_CONFIG"; return 0; fi
|
|
32
32
|
if [ -n "${SDLC_HUB_CONFIG:-}" ]; then printf '%s' "$SDLC_HUB_CONFIG"; return 0; fi
|
|
33
33
|
if [ -f .sdlc/product.json ] && [ -f .sdlc/hub.json ] && ! cmp -s .sdlc/product.json .sdlc/hub.json; then
|
|
34
|
-
echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5.
|
|
34
|
+
echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. In the Product, run \`yad migrate --apply --keep product\` (or \`--keep hub\`) to choose the copy to keep, then commit both files." >&2
|
|
35
35
|
return 1
|
|
36
36
|
fi
|
|
37
37
|
if [ -f .sdlc/product.json ]; then printf '%s' .sdlc/product.json; else printf '%s' .sdlc/hub.json; fi
|
|
@@ -92,7 +92,7 @@ BASE="${ARGS[0]:-${SDLC_BASE:-$(resolve_base)}}"
|
|
|
92
92
|
|
|
93
93
|
# Fail closed if the base ref can't be resolved (shallow clone / wrong base branch / unfetched ref).
|
|
94
94
|
if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
|
|
95
|
-
echo "FAIL [commit-message]: base ref '${BASE}' not found —
|
|
95
|
+
echo "FAIL [commit-message]: base ref '${BASE}' not found — check the code out with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), and give a base that names a fetched branch (the first argument, or SDLC_BASE)."
|
|
96
96
|
exit 1
|
|
97
97
|
fi
|
|
98
98
|
RANGE="${BASE}..HEAD"
|
|
@@ -142,4 +142,10 @@ done <<EOF
|
|
|
142
142
|
$commits
|
|
143
143
|
EOF
|
|
144
144
|
|
|
145
|
+
# Every failure above is fixed the same way: the commit is reworded, which rewrites it, so the branch is
|
|
146
|
+
# force-pushed. Said once, with the real base, after the list (#386).
|
|
147
|
+
if [ "$rc" -ne 0 ]; then
|
|
148
|
+
echo " -> Reword each commit listed above: \`git commit --amend\` for the last one, or \`git rebase -i ${BASE}\` (mark it 'reword') for an older one; then force-push the branch (\`git push --force-with-lease\`)."
|
|
149
|
+
fi
|
|
150
|
+
|
|
145
151
|
exit "$rc"
|