yadflow 4.7.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.
Files changed (77) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/README.md +43 -4
  3. package/bin/commands.mjs +4 -1
  4. package/bin/yad.mjs +147 -20
  5. package/cli/agent-guard.mjs +511 -0
  6. package/cli/agent-guide.mjs +83 -0
  7. package/cli/agent-rules.mjs +381 -0
  8. package/cli/argv-flags.mjs +7 -0
  9. package/cli/ci-check.mjs +492 -0
  10. package/cli/docs.mjs +1 -1
  11. package/cli/doctor.mjs +43 -7
  12. package/cli/epic-state.mjs +3 -3
  13. package/cli/errors.mjs +1 -0
  14. package/cli/guide.mjs +549 -0
  15. package/cli/hook.mjs +32 -3
  16. package/cli/lib.mjs +46 -0
  17. package/cli/lifecycle/defaults/2.json +124 -0
  18. package/cli/lifecycle/lifecycle.schema.json +5 -2
  19. package/cli/lifecycle.mjs +16 -3
  20. package/cli/manifest.mjs +75 -0
  21. package/cli/marked-block.mjs +48 -0
  22. package/cli/members.mjs +19 -5
  23. package/cli/migrate.mjs +17 -19
  24. package/cli/next.mjs +1 -1
  25. package/cli/plan.mjs +326 -22
  26. package/cli/protection.mjs +50 -0
  27. package/cli/reconcile.mjs +187 -26
  28. package/cli/report.mjs +62 -14
  29. package/cli/setup.mjs +244 -25
  30. package/cli/signing.mjs +377 -0
  31. package/cli/test-agents-file.mjs +993 -0
  32. package/cli/test-ci-check.mjs +616 -0
  33. package/cli/test-guide.mjs +1267 -0
  34. package/cli/test-node.mjs +129 -0
  35. package/cli/test-setup-agent.mjs +352 -0
  36. package/cli/test-signing.mjs +524 -0
  37. package/cli/toolbox.mjs +1 -1
  38. package/cli/update-commit.mjs +313 -11
  39. package/cli/workspace.mjs +37 -12
  40. package/package.json +6 -4
  41. package/skills/sdlc/config.yaml +4 -4
  42. package/skills/sdlc/module-help.csv +1 -0
  43. package/skills/yad-change/SKILL.md +3 -2
  44. package/skills/yad-checks/SKILL.md +29 -9
  45. package/skills/yad-checks/references/check-gates.md +9 -4
  46. package/skills/yad-checks/templates/checks/package-manager.sh +1 -1
  47. package/skills/yad-checks/templates/github/yad-checks.yml +1 -1
  48. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +1 -1
  49. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +1 -1
  50. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +1 -1
  51. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -1
  52. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +1 -1
  53. package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
  54. package/skills/yad-commit/SKILL.md +4 -3
  55. package/skills/yad-connect-repos/SKILL.md +5 -3
  56. package/skills/yad-connect-repos/references/code-context.md +2 -1
  57. package/skills/yad-connect-repos/references/repos-registry.md +2 -1
  58. package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
  59. package/skills/yad-engineer-review/SKILL.md +12 -7
  60. package/skills/yad-engineer-review/references/ship-and-record.md +7 -4
  61. package/skills/yad-epic/SKILL.md +2 -1
  62. package/skills/yad-epic/references/state-schema.md +1 -1
  63. package/skills/yad-guide/SKILL.md +192 -0
  64. package/skills/yad-open-pr/SKILL.md +1 -1
  65. package/skills/yad-pair-review/SKILL.md +14 -5
  66. package/skills/yad-product-bridge/SKILL.md +32 -13
  67. package/skills/yad-product-bridge/references/bridge.md +6 -3
  68. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
  69. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +1 -1
  70. package/skills/yad-report/SKILL.md +15 -0
  71. package/skills/yad-review-companion/SKILL.md +5 -3
  72. package/skills/yad-review-gate/SKILL.md +13 -9
  73. package/skills/yad-review-gate/references/gating.md +1 -1
  74. package/skills/yad-run/SKILL.md +10 -6
  75. package/skills/yad-run/references/run-loop.md +2 -1
  76. package/skills/yad-sync-repos/SKILL.md +2 -1
  77. package/skills/yad-ui/SKILL.md +2 -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`.
@@ -188,10 +188,11 @@ the Shape phases will now load this repo's code-map. Nothing auto-advances; this
188
188
 
189
189
  - **`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
190
  `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
191
+ `code-map.md` (Step 3), publish it to the Product with **`yad repo refresh <repo> --push`** — ask the
192
+ person first, every time: it pushes to the default branch (E158) — it
192
193
  commits the tracked code-maps + `.sdlc/repos.json` (never the gitignored `pack.md`) as one
193
194
  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).
195
+ straight to the Product's **default branch** (add `--allow-branch` to commit on a non-default branch, only when the person asks).
195
196
  This is the code-context analogue of `yad checkpoint` — human-owned machine state, no Task trailer,
196
197
  no Co-Authored-By.
197
198
  - **`list`** — print every registry entry with a **fresh/stale** flag: compare each repo's current HEAD
@@ -253,7 +254,8 @@ any user name or password taken out of `git_url`) into every connected repo, and
253
254
  to each repo's default branch — a record on disk that is not committed as it stands is committed by the
254
255
  next `--push`, though `yad check` reads it as `ok`. The Product-reading gates read it from
255
256
  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
257
+ repo, run `yad check --fix --open-pr` (a PR/MR per repo, no asking), or `yad check --fix --push` after the
258
+ person says yes (it pushes to every repo's default branch, E158); `yad doctor` warns `repos:product-link-missing` until it is on
257
259
  the repo's default branch.
258
260
 
259
261
  ## 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
@@ -126,11 +126,13 @@ the gate talks only through files; refuse to treat AI review as a human approval
126
126
  ### Step 3 — `ship` (merge + record + update state)
127
127
  Ship **iff ALL hold**: the check gates pass (Step C), the AI review has run (advisory), and the
128
128
  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).
129
+ - **Merge** the task branch into the repo's default branch. The person merges it, never you, even when
130
+ your login could (E158): give them the PR/MR link, wait, then confirm by reading
131
+ (`yad build merged … --ship`).
130
132
  - **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).
133
+ `status: skipped`, it was set aside as needing no change: stop and tell the person. Only when they say
134
+ the lane is owed after all, run `yad unskip <epic> <story> --repo <repo>` before recording a ship
135
+ (E158), so the two records never say opposite things (`yad doctor` fails that as `lane:…:contradiction`; `yad checkpoint --retro-ship` refuses it).
134
136
  - **See whether it merged — ask, do not wait (#355).** The merge is a person's, but you do not need them
135
137
  to tell you it happened: run `yad build merged <story> --task <task> --repo <repo> --ship`. It asks the
136
138
  platform about the task's PR/MR (found by its branch; `--pr <n>` names it) and answers one `state`
@@ -147,14 +149,16 @@ engineer-review rule is satisfied (Step 2). Then:
147
149
  (`followUps`), never a second ship. Shape: `references/ship-and-record.md`.
148
150
  - **Catch up on merges (#365)** — `yad build sync [<epic>]` records every ship the code repos already show
149
151
  (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`.
152
+ for each story now fully shipped; it lists what it cannot record. Then ask the person before
153
+ `yad checkpoint --push`: it pushes to the default branch, which is asked about every time (E158).
151
154
  - **Record the ship** — `yad build ship <story> --task <task> --repo <repo> --pr <n>` (what `--ship` runs),
152
155
  once the PR/MR has merged. A grouped PR (#350) — several small tasks of one story — ships each task it
153
156
  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
157
  engagement signal), the body's `Risk level:` and the merge date from the platform, refuses a PR that is
155
158
  not merged or that comes from another task's branch, and writes the ship to its own shard
156
159
  `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
160
+ repo whose platform cannot be read records it by hand: `--merge-commit <sha> --approver <login>`, only with
161
+ the merge commit and approvers the person gave you, never guessed (E158). A
158
162
  task merged with no PR/MR: `--merge-commit <sha>` and no `--pr` (the commit must be on the default
159
163
  branch and name the task in its `Task:` trailer or subject; the platform is asked whether a PR merged it,
160
164
  and a PR that did is named instead). It moves the story to `in-build`. Never write the shard by hand.
@@ -176,7 +180,8 @@ engineer-review rule is satisfied (Step 2). Then:
176
180
  word on the trust signal: a diff merged as authored is `approved-unchanged`; one the engineer edited
177
181
  before merge is `approved-with-edits`; a rejected one is `rejected`. This is the run record `yad dial`
178
182
  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
183
+ - **Commit the machine-written ledgers.** Ask the person, then run `yad checkpoint --push` from `{project-root}`
184
+ (a push to the default branch is asked about every time, E158) to commit
180
185
  the Build ledgers just written (the `build-log/` shard, and the `trust-log/` shard /
181
186
  `build-state/<story>.json` if the story ran through `yad-run`) as one `chore(product): …` audit-trail
182
187
  commit — default branch only, staging the shard dirs (`yad tidy up` folds finished shards later),
@@ -103,7 +103,7 @@ about follow-ups (`…-T03-followup-reminders`). A follow-up is opened by a pers
103
103
  This is the Build analogue of Shape's `approvals.json` — files only, no hidden state, so a
104
104
  future service can drive ship by writing the same records. Like the trust log and build-state, it is a
105
105
  machine-written ledger committed by **`yad checkpoint`** (the Build analogue of `yad gate` sync),
106
- not by hand: after recording the ship, `yad checkpoint --push` lands the new `build-log/` shard as a
106
+ not by hand: after recording the ship, `yad checkpoint --push` (after the person's yes, E158) lands the new `build-log/` shard as a
107
107
  `chore(product): …` audit-trail commit on the default branch (allowlist-scoped to the Build ledgers,
108
108
  never a Shape gate file); `yad tidy up` folds finished shards into `build-log.json` later.
109
109
 
@@ -113,7 +113,8 @@ A story that was merged and shipped **before** the Build ledger existed has no b
113
113
  `yad checkpoint` can't carry its `status: shipped` flip (the flip is only carried when a ship backs it,
114
114
  #112) — leaving a raw `git push origin main` as the only way to land it, against the never-raw-git
115
115
  convention. To reconcile it through yad, record a **retroactive** ship, then checkpoint carries the flip
116
- in the same commit:
116
+ in the same commit. Record one only when the person asked for a retroactive ship, and ask every time
117
+ before `--push`: it lands on the default branch (E158).
117
118
 
118
119
  ```
119
120
  yad checkpoint --retro-ship <epic>/<story> --repo <r> [--task <t>] [--merge-commit <sha>] [--push]
@@ -136,7 +137,8 @@ indefinitely — which is precisely why reading the folded file alone is never s
136
137
 
137
138
  **One repo per run (#166).** A ship is recorded per `(story, task, repo)`, so a story that shipped in
138
139
  several repos needs one retroactive shard **per repo** — the guard is keyed on `(story, repo)`, not on
139
- the story alone, so recording the first repo never locks out the rest. Re-run once per repo:
140
+ the story alone, so recording the first repo never locks out the rest. Re-run once per repo, asking
141
+ before each `--push`:
140
142
 
141
143
  ```
142
144
  yad checkpoint --retro-ship EP-foo/EP-foo-S01 --repo web --push
@@ -186,7 +188,8 @@ The story frontmatter `status` reflects build progress:
186
188
 
187
189
  You write this flip into `stories/<story>.md`, but **do not hand-commit it** — the next
188
190
  `yad checkpoint --push` carries it in the same `chore(product)` commit as the ledgers (the story now has a
189
- build-log ship, so checkpoint stages it; #112). This is what keeps the story artifact from drifting
191
+ build-log ship, so checkpoint stages it; #112; it pushes to the default branch, so an AI agent asks the
192
+ person first, every time, E158). This is what keeps the story artifact from drifting
190
193
  from the build ledger, so there is never a reason to fall back to a raw `git push origin main`.
191
194
 
192
195
  So the chain is traceable both ways: from the epic down (`epic.md` → `stories/<story>.md` →
@@ -229,7 +229,8 @@ Notes:
229
229
  every later change to it is CI's. See `references/state-schema.md`, "Authoring branches".
230
230
  - **No UI?** Seed the chain **as-is** (the two `ui-design` steps are always in it). If this epic has no
231
231
  user-facing surface (a backend/API service, data pipeline, infra), the `ui-design` step is optional
232
- and can be marked N/A now with `yad skip EP-<slug> ui-design --reason "<why>"` — it stays visible,
232
+ and can be marked N/A now: offer it, and on the person's yes run `yad skip EP-<slug> ui-design --reason "<why>"` (a
233
+ skip is the person's decision, E158) — it stays visible,
233
234
  short-circuits its gate, and advances straight to `stories` when architecture is approved. It is
234
235
  reversible with `yad unskip EP-<slug> ui-design` until the stories review opens. **On a verified Product, now is the only time:** once this epic's first review PR merges, CI owns `state.json` and `yad skip` refuses. Don't hand-edit the chain to drop the steps;
235
236
  the skip is the single, auditable mechanism (see `references/state-schema.md` → "ui-design is optional").
@@ -96,7 +96,7 @@ Each `steps[]` entry:
96
96
  ### The step catalogue
97
97
 
98
98
  Every one of those ids is defined in **one place** — the lifecycle default that ships with yadflow,
99
- `cli/lifecycle/defaults/1.json` (E134). The engine reads it as `STEPS` in `cli/epic-state.mjs` (E4):
99
+ `cli/lifecycle/defaults/2.json` (E134; 2.json added each step's description and driver, E157). The engine reads it as `STEPS` in `cli/epic-state.mjs` (E4):
100
100
  there, each author step with a gate becomes two rows, the step and its `<id>-review` gate. A row says which phase the step is in, whether it authors an artifact or gates one, which file it
101
101
  writes, which skill runs it, and — for a gate — which step it reviews. The phase table, the skill
102
102
  tables and the Build order are all views of it, held to it by tests, so a step cannot exist in one and