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.
Files changed (96) hide show
  1. package/CHANGELOG.md +116 -0
  2. package/README.md +43 -4
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +169 -22
  5. package/cli/agent-guard.mjs +511 -0
  6. package/cli/agent-guide.mjs +83 -0
  7. package/cli/agent-rules.mjs +388 -0
  8. package/cli/argv-flags.mjs +7 -0
  9. package/cli/build.mjs +1 -1
  10. package/cli/ci-check.mjs +492 -0
  11. package/cli/docs.mjs +1 -1
  12. package/cli/doctor.mjs +148 -7
  13. package/cli/epic-state.mjs +3 -3
  14. package/cli/errors.mjs +1 -0
  15. package/cli/guide.mjs +549 -0
  16. package/cli/hook.mjs +32 -3
  17. package/cli/lib.mjs +46 -0
  18. package/cli/lifecycle/defaults/2.json +124 -0
  19. package/cli/lifecycle/lifecycle.schema.json +5 -2
  20. package/cli/lifecycle.mjs +16 -3
  21. package/cli/machine.mjs +141 -0
  22. package/cli/manifest.mjs +75 -0
  23. package/cli/marked-block.mjs +48 -0
  24. package/cli/members.mjs +19 -5
  25. package/cli/migrate.mjs +17 -19
  26. package/cli/next.mjs +1 -1
  27. package/cli/openpr.mjs +46 -6
  28. package/cli/plan.mjs +326 -22
  29. package/cli/preview.mjs +253 -0
  30. package/cli/protection.mjs +50 -0
  31. package/cli/reconcile.mjs +187 -26
  32. package/cli/repo.mjs +64 -3
  33. package/cli/report.mjs +62 -14
  34. package/cli/review.mjs +4 -0
  35. package/cli/setup.mjs +244 -25
  36. package/cli/signing.mjs +377 -0
  37. package/cli/story-frames.mjs +296 -0
  38. package/cli/test-agents-file.mjs +993 -0
  39. package/cli/test-ci-check.mjs +616 -0
  40. package/cli/test-guide.mjs +1267 -0
  41. package/cli/test-machine.mjs +140 -0
  42. package/cli/test-node.mjs +129 -0
  43. package/cli/test-preview.mjs +511 -0
  44. package/cli/test-setup-agent.mjs +352 -0
  45. package/cli/test-signing.mjs +524 -0
  46. package/cli/test-story-frames.mjs +339 -0
  47. package/cli/toolbox.mjs +35 -1
  48. package/cli/update-commit.mjs +313 -11
  49. package/cli/workspace.mjs +37 -12
  50. package/package.json +6 -4
  51. package/skills/sdlc/config.yaml +4 -4
  52. package/skills/sdlc/module-help.csv +1 -0
  53. package/skills/yad-change/SKILL.md +3 -2
  54. package/skills/yad-checks/SKILL.md +29 -9
  55. package/skills/yad-checks/references/check-gates.md +9 -4
  56. package/skills/yad-checks/templates/checks/package-manager.sh +1 -1
  57. package/skills/yad-checks/templates/github/yad-checks.yml +1 -1
  58. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +1 -1
  59. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +1 -1
  60. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +1 -1
  61. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -1
  62. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +1 -1
  63. package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
  64. package/skills/yad-commit/SKILL.md +4 -3
  65. package/skills/yad-connect-design/SKILL.md +7 -4
  66. package/skills/yad-connect-design/references/design-context.md +23 -0
  67. package/skills/yad-connect-design/references/design-registry.md +3 -3
  68. package/skills/yad-connect-repos/SKILL.md +13 -3
  69. package/skills/yad-connect-repos/references/code-context.md +2 -1
  70. package/skills/yad-connect-repos/references/repos-registry.md +2 -1
  71. package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
  72. package/skills/yad-engineer-review/SKILL.md +25 -7
  73. package/skills/yad-engineer-review/references/ship-and-record.md +7 -4
  74. package/skills/yad-epic/SKILL.md +2 -1
  75. package/skills/yad-epic/references/state-schema.md +7 -1
  76. package/skills/yad-guide/SKILL.md +192 -0
  77. package/skills/yad-implement/SKILL.md +14 -0
  78. package/skills/yad-open-pr/SKILL.md +5 -2
  79. package/skills/yad-pair-review/SKILL.md +19 -5
  80. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -0
  81. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -0
  82. package/skills/yad-product-bridge/SKILL.md +32 -13
  83. package/skills/yad-product-bridge/references/bridge.md +6 -3
  84. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
  85. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +1 -1
  86. package/skills/yad-report/SKILL.md +15 -0
  87. package/skills/yad-review-companion/SKILL.md +9 -4
  88. package/skills/yad-review-gate/SKILL.md +13 -9
  89. package/skills/yad-review-gate/references/gating.md +1 -1
  90. package/skills/yad-run/SKILL.md +10 -6
  91. package/skills/yad-run/references/run-loop.md +2 -1
  92. package/skills/yad-spec/SKILL.md +21 -0
  93. package/skills/yad-stories/SKILL.md +22 -0
  94. package/skills/yad-stories/references/story-schema.md +1 -0
  95. package/skills/yad-sync-repos/SKILL.md +2 -1
  96. 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 `yad check --fix --push` has merged `.sdlc/product-link.json` into
39
- the code repo (E120): the gates read it from the base first, and `checks/product-checkout.sh` clones
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 20, 22 or 24 line — for example from nvm)
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, then run `yad update --overwrite-local` to restore the fragment (it keeps
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
- Commit the wiring on the repo's default branch (it is shared infrastructure, not a task diff).
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`. `yad setup` and `yad check --fix` install them; nothing by hand.
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. `YAD_HOOK_DISABLE=1`
276
- skips one command. A PERSON who must commit a ledger change anyway uses `yad commit --manual --reason
277
- "<why>"` (E49) — never the agent on its own initiative.
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 20, 22 or 24 line (or install a current Corepack first). The installer
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 --push`: it writes `.sdlc/product-link.json` into each
706
- connected code repo and commits it to the default branch. Set the Product's `git_url` in its
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. `YAD_HOOK_DISABLE=1` skips one command.
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 20, 22 or 24 line, or install a current Corepack first (npm install -g corepack)"
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 20, 22 or 24 line (Node 25+ has no Corepack)
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 20, 22 or 24 line; Node 25+ has no Corepack)
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 20, 22 or 24 line; Node 25+ has no Corepack).
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 20, 22 or 24 line). A shell-executor runner
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 20, 22 or 24 line). A shell-executor runner
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 20, 22 or 24 line). A shell-executor runner
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` on your own initiative.** Committing past the ledger hook is a person's decision.
81
- Pass it only when the user asked for it, with the reason they gave. `--manual` needs `--reason`, and the
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, e.g. `figma-mcp` | `html-to-design` | `pencil-mcp`) and whether it
71
- is available. **Auth is the local user's own** — the user's authenticated MCP session. The skill
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-mcp",
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-mcp"
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-mcp", // the concrete MCP: figma-mcp | html-to-design | pencil-mcp | null
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-mcp" // the MCP detected at connect | unavailable (degraded)
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-mcp` / `pencil-mcp` / …) means
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`**: it
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 --push`; `yad doctor` warns `repos:product-link-missing` until it is on
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). The `pack.md` is gitignored — `yad repo refresh`/`yad setup` scaffold
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 has no phase: it is
60
- a CLI helper, not a pipeline step.
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 (the human performs/authorises the merge).
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, and run
132
- `yad unskip <epic> <story> --repo <repo>` before recording a ship, so the two records never say opposite
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. Commit with `yad checkpoint --push`.
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>`. A
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.** Run `yad checkpoint --push` from `{project-root}` to commit
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),