yadflow 4.0.0-next.3 → 4.0.0

package/skills/yad-checks/templates/checks/verified-commits.sh

@@ -25,11 +25,35 @@
 # GITLAB_TOKEN (or SDLC_API_TOKEN) with read_api scope; see the pipeline fragment header.
 set -euo pipefail
 
+# --- shared Product settings file (byte-identical across the gates; they are standalone by design, so
+# --- it is duplicated, not sourced) ---
+# The Product's settings live under two names until v5: `.sdlc/product.json`, read first from 4.0, and
+# `.sdlc/hub.json`, which an older yadflow wrote and its gates read. The environment may name the file
+# instead: SDLC_PRODUCT_CONFIG, or the older SDLC_HUB_CONFIG. Two names that say different things are
+# never settled by picking one — the CLI refuses the same way (YAD-STATE-008) — so the gate FAILS and
+# names both. Said on stderr and returned as a failure: this runs inside `$(...)`, where an `exit` would
+# only leave the subshell. `cmp -s` is byte for byte, like the CLI's own comparison.
+product_config() {
+  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ] && [ -n "${SDLC_HUB_CONFIG:-}" ] \
+    && [ "$SDLC_PRODUCT_CONFIG" != "$SDLC_HUB_CONFIG" ] && ! cmp -s "$SDLC_PRODUCT_CONFIG" "$SDLC_HUB_CONFIG"; then
+    echo "FAIL [product-settings]: SDLC_PRODUCT_CONFIG (${SDLC_PRODUCT_CONFIG}) and SDLC_HUB_CONFIG (${SDLC_HUB_CONFIG}) name files that say different things. Set only SDLC_PRODUCT_CONFIG." >&2
+    return 1
+  fi
+  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ]; then printf '%s' "$SDLC_PRODUCT_CONFIG"; return 0; fi
+  if [ -n "${SDLC_HUB_CONFIG:-}" ]; then printf '%s' "$SDLC_HUB_CONFIG"; return 0; fi
+  if [ -f .sdlc/product.json ] && [ -f .sdlc/hub.json ] && ! cmp -s .sdlc/product.json .sdlc/hub.json; then
+    echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. Run \`yad migrate\` in the Product to choose the copy to keep, and commit both." >&2
+    return 1
+  fi
+  if [ -f .sdlc/product.json ]; then printf '%s' .sdlc/product.json; else printf '%s' .sdlc/hub.json; fi
+}
+PRODUCT_CONFIG="$(product_config)" || exit 1
+
 # --- shared base resolution (byte-identical across the gates; they are standalone by design, so it
 # --- is duplicated, not sourced) ---
 # With no explicit base, RESOLVE the trunk instead of assuming a hardcoded `origin/main` — on a repo
 # whose trunk is `develop`/`master` that guess either fails closed or, where a stale `main` still
-# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/hubcommit.mjs,
+# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/productcommit.mjs,
 # cli/repo.mjs): the CONFIGURED default_branch first, then the remote's published default
 # (origin/HEAD), then origin/main. Each candidate must actually resolve before it is used, so a
 # DANGLING origin/HEAD (trunk renamed, the old remote-tracking ref pruned) falls through to the next
@@ -38,7 +62,7 @@ set -euo pipefail
 # command substitution in an assignment aborts the script.
 resolve_base() {
   # tr first: a key and its value may legally sit on separate lines, which a per-line match misses.
-  _cfg="$(tr -d '\n' < "${SDLC_HUB_CONFIG:-.sdlc/hub.json}" 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
+  _cfg="$({ tr -d '\n' < "$PRODUCT_CONFIG"; } 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
   _head="$(git symbolic-ref --short --quiet refs/remotes/origin/HEAD 2>/dev/null)" || _head=""
   for _c in "origin/${_cfg}" "${_head}" origin/main; do
     case "$_c" in ''|origin/) continue ;; esac

package/skills/yad-checks/templates/github/yad-checks.yml

@@ -12,12 +12,16 @@ on:
     types: [opened, synchronize, reopened, edited]
     branches: ["**"]
 
+# Read-only by default: no gate here writes to the repo. A job that needs more asks for it itself.
+permissions:
+  contents: read
+
 jobs:
   spec-link:
     runs-on: ubuntu-latest
     if: github.event.action != 'edited'
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
       - run: bash checks/spec-link.sh "origin/${{ github.base_ref }}"
 
@@ -25,8 +29,12 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event.action != 'edited'
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
+      # E120: check the Product out where .sdlc/product-link.json says, when the YAD_PRODUCT_TOKEN
+      # secret is set; without it this prints a note and the gate defers, as before.
+      - run: bash checks/product-checkout.sh "origin/${{ github.base_ref }}"
+        env: { YAD_PRODUCT_TOKEN: "${{ secrets.YAD_PRODUCT_TOKEN }}" }
       - run: bash checks/contract-check.sh "origin/${{ github.base_ref }}"
 
   # E65/E66 — the risk map (.sdlc/risk-map: a risk level per directory, no names). Warnings, and the
@@ -36,7 +44,7 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event.action != 'edited'
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
       - run: bash checks/risk-map-check.sh "origin/${{ github.base_ref }}"
 
@@ -50,11 +58,11 @@ jobs:
       NX_HEAD: ${{ github.event.pull_request.head.sha }}
       COREPACK_HOME: ${{ github.workspace }}/.corepack-cache # pinned-manager downloads, cached below
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with:
           fetch-depth: 0
           filter: blob:none
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: ${{ env.YAD_NODE_VERSION }}
       # Dependency cache for either manager: npm's ~/.npm, pnpm's content-addressable store, and the
@@ -63,7 +71,7 @@ jobs:
       # package.json, since a packageManager bump changes no lockfile. setup-node's own `cache:` must
       # name the manager up front (and needs pnpm on PATH before it runs), which package.json only
       # decides later — so cache the directories directly.
-      - uses: actions/cache@v4
+      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
           path: |
             ~/.npm
@@ -82,24 +90,36 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event.action != 'edited'
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
+      # E120: check the Product out where .sdlc/product-link.json says, when the YAD_PRODUCT_TOKEN
+      # secret is set; without it this prints a note and the gate defers, as before.
+      - run: bash checks/product-checkout.sh "origin/${{ github.base_ref }}"
+        env: { YAD_PRODUCT_TOKEN: "${{ secrets.YAD_PRODUCT_TOKEN }}" }
       - run: bash checks/lineage-check.sh "origin/${{ github.base_ref }}"
 
   epic-open:
     runs-on: ubuntu-latest
     if: github.event.action != 'edited'
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
+      # E120: check the Product out where .sdlc/product-link.json says, when the YAD_PRODUCT_TOKEN
+      # secret is set; without it this prints a note and the gate defers, as before.
+      - run: bash checks/product-checkout.sh "origin/${{ github.base_ref }}"
+        env: { YAD_PRODUCT_TOKEN: "${{ secrets.YAD_PRODUCT_TOKEN }}" }
       - run: bash checks/epic-open.sh "origin/${{ github.base_ref }}"
 
   reconcile-debt:
     runs-on: ubuntu-latest
     if: github.event.action != 'edited'
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
+      # E120: check the Product out where .sdlc/product-link.json says, when the YAD_PRODUCT_TOKEN
+      # secret is set; without it this prints a note and the gate defers, as before.
+      - run: bash checks/product-checkout.sh "origin/${{ github.base_ref }}"
+        env: { YAD_PRODUCT_TOKEN: "${{ secrets.YAD_PRODUCT_TOKEN }}" }
       - run: bash checks/reconcile-debt-check.sh "origin/${{ github.base_ref }}"
 
   # Pattern gates: commit subject + PR title + PR body all follow the convention (profile: code).
@@ -108,7 +128,7 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event.action != 'edited'
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
       - run: bash checks/commit-message.sh --profile code "origin/${{ github.base_ref }}"
 
@@ -118,7 +138,7 @@ jobs:
     env:
       PR_TITLE: ${{ github.event.pull_request.title }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
       - run: bash checks/pr-title.sh --profile code "$PR_TITLE"
 
   pr-template:
@@ -126,7 +146,7 @@ jobs:
     env:
       PR_BODY: ${{ github.event.pull_request.body }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
       - run: |
           body="$(mktemp)"; printf '%s' "$PR_BODY" > "$body"
           bash checks/pr-template.sh --profile code "$body"
@@ -141,6 +161,6 @@ jobs:
     env:
       GH_TOKEN: ${{ github.token }} # read-only: gh api commits/<sha> for the Verified badge
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
       - run: bash checks/verified-commits.sh "origin/${{ github.base_ref }}"

package/skills/yad-checks/templates/github/{yad-hub-checks.yml → yad-product-checks.yml}

@@ -1,12 +1,12 @@
 # yad-managed: yad-checks
-# Pattern gates for the PRODUCT. They run with `--profile hub` and split by head branch:
+# Pattern gates for the PRODUCT. They run with `--profile product` and split by head branch:
 #   review/EP-* PRs are Shape artifact-review vehicles — a `review: <artifact> (EP-<slug>)` title
 #     and the Product artifact-review template body.
 #   every other PR is a tooling/code change to the Product itself — a Conventional-Commits title and the
 #     code task template body (same convention the code repos use).
 # The head ref is passed via --head so the gate can tell the two apart. Commit subjects are always
 # Conventional-Commits. Standalone workflow so it never collides with the code-repo yad-checks workflow.
-name: yad-hub-checks
+name: yad-product-checks
 on:
   pull_request:
     # `edited` (beyond the opened/synchronize/reopened defaults) so a PR title/body correction
@@ -14,6 +14,10 @@ on:
     types: [opened, synchronize, reopened, edited]
     branches: ["**"]
 
+# Read-only by default: no gate here writes to the repo. A job that needs more asks for it itself.
+permissions:
+  contents: read
+
 jobs:
   # commit-message + ledger-guard read the commit range, not the PR title/body — skip them on a bare
   # `edited` event (only pr-title/pr-template need to re-check a title/body fix).
@@ -21,9 +25,9 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event.action != 'edited'
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
-      - run: bash checks/commit-message.sh --profile hub "origin/${{ github.base_ref }}"
+      - run: bash checks/commit-message.sh --profile product "origin/${{ github.base_ref }}"
 
   # Pass the title via env (never interpolate untrusted ${{ }} into a run line — injection-safe).
   # fetch-depth: 0 + the base ref give us the PR's changed paths, so the gate can reject an artifact
@@ -35,11 +39,11 @@ jobs:
       PR_HEAD: ${{ github.event.pull_request.head.ref }}
       BASE_REF: ${{ github.base_ref }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
       - run: |
           changed="$(mktemp)"; git -c core.quotePath=false diff --no-renames --name-only "origin/${BASE_REF}...HEAD" > "$changed"
-          bash checks/pr-title.sh --profile hub --head "$PR_HEAD" --changed "$changed" "$PR_TITLE"
+          bash checks/pr-title.sh --profile product --head "$PR_HEAD" --changed "$changed" "$PR_TITLE"
 
   pr-template:
     runs-on: ubuntu-latest
@@ -48,20 +52,20 @@ jobs:
       PR_HEAD: ${{ github.event.pull_request.head.ref }}
       BASE_REF: ${{ github.base_ref }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
       - run: |
           changed="$(mktemp)"; git -c core.quotePath=false diff --no-renames --name-only "origin/${BASE_REF}...HEAD" > "$changed"
           body="$(mktemp)"; printf '%s' "$PR_BODY" > "$body"
-          bash checks/pr-template.sh --profile hub --head "$PR_HEAD" --changed "$changed" "$body"
+          bash checks/pr-template.sh --profile product --head "$PR_HEAD" --changed "$changed" "$body"
 
-  # The gate ledger is CI-owned: reject non-bot commits to .sdlc/{state,approvals,comments,hub-prs}.json
+  # The gate ledger is CI-owned: reject non-bot commits to .sdlc/{state,approvals,comments,product-prs,hub-prs}.json
   # or reviews/*.md (.sdlc/contract-lock.json is artifact-side and allowed). The one other exception is a
   # brand-new epic's seed, which no CI path can write, so it rides this first review PR (#162).
   ledger-guard:
     runs-on: ubuntu-latest
     if: github.event.action != 'edited'
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
       - run: bash checks/ledger-guard.sh "origin/${{ github.base_ref }}"

package/skills/yad-checks/templates/github/yad-update-guard.yml

@@ -30,7 +30,7 @@ jobs:
     env:
       GH_TOKEN: ${{ github.token }} # read-only: gh api commits/<sha> for the Verified badge
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
       - name: Resolve the pushed range base
         id: base

package/skills/yad-checks/templates/github/yad-verified-commits.yml

@@ -17,6 +17,6 @@ jobs:
     env:
       GH_TOKEN: ${{ github.token }} # read-only: gh api commits/<sha> for the Verified badge
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
       - run: bash checks/verified-commits.sh "origin/${{ github.base_ref }}"

package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml

@@ -51,6 +51,9 @@ yad-contract-check:
   extends: .sdlc_mr_only
   needs: []
   script:
+    # E120: check the Product out where .sdlc/product-link.json says, when the YAD_PRODUCT_TOKEN CI/CD
+    # variable is set (masked); without it this prints a note and the gate defers, as before.
+    - bash checks/product-checkout.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
     - bash checks/contract-check.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
 
 # E65/E66 — the risk map (.sdlc/risk-map: a risk level per directory, no names). Warnings, and the
@@ -77,18 +80,27 @@ yad-lineage-check:
   extends: .sdlc_mr_only
   needs: []
   script:
+    # E120: check the Product out where .sdlc/product-link.json says, when the YAD_PRODUCT_TOKEN CI/CD
+    # variable is set (masked); without it this prints a note and the gate defers, as before.
+    - bash checks/product-checkout.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
     - bash checks/lineage-check.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
 
 yad-epic-open:
   extends: .sdlc_mr_only
   needs: []
   script:
+    # E120: check the Product out where .sdlc/product-link.json says, when the YAD_PRODUCT_TOKEN CI/CD
+    # variable is set (masked); without it this prints a note and the gate defers, as before.
+    - bash checks/product-checkout.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
     - bash checks/epic-open.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
 
 yad-reconcile-debt:
   extends: .sdlc_mr_only
   needs: []
   script:
+    # E120: check the Product out where .sdlc/product-link.json says, when the YAD_PRODUCT_TOKEN CI/CD
+    # variable is set (masked); without it this prints a note and the gate defers, as before.
+    - bash checks/product-checkout.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
     - bash checks/reconcile-debt-check.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
 
 # Pattern gates: commit subject + MR title + MR body all follow the convention (profile: code).

package/skills/yad-checks/templates/gitlab/{yad-hub-checks.gitlab-ci.yml → yad-product-checks.gitlab-ci.yml}

@@ -2,53 +2,53 @@
 # Pattern gates for the PRODUCT, as an INCLUDABLE fragment. Pulled into the Product's root
 # .gitlab-ci.yml via:
 #   include:
-#     - local: '.gitlab/ci/yad-hub-checks.yml'
-# MRs run with `--profile hub` and split by source branch: review/EP-* MRs are Shape artifact-
+#     - local: '.gitlab/ci/yad-product-checks.yml'
+# MRs run with `--profile product` and split by source branch: review/EP-* MRs are Shape artifact-
 # review vehicles (a `review: <artifact> (EP-<slug>)` title + the Product artifact-review template body);
 # every other MR is a tooling/code change to the Product itself and follows the code convention (a
 # Conventional-Commits title + the code task template body). The source branch is passed via --head so
 # the gate can tell the two apart. Commit subjects are always Conventional-Commits.
-# Job names are yad-hub-prefixed so they coexist with any code-repo fragment in one pipeline; jobs use
+# Job names are yad-product-prefixed so they coexist with any code-repo fragment in one pipeline; jobs use
 # `needs: []` and no `stage:` so a foreign `stages:` list can neither break nor reorder them.
 default:
   image: node:20
   tags: [$YAD_RUNNER_TAGS]
 
-.yad_hub_mr_only:
+.yad_product_mr_only:
   rules:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
 
 variables:
   GIT_DEPTH: "0"   # full history so the commit gate can diff against the target branch
 
-yad-hub-commit-message:
-  extends: .yad_hub_mr_only
+yad-product-commit-message:
+  extends: .yad_product_mr_only
   needs: []
   script:
-    - bash checks/commit-message.sh --profile hub "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+    - bash checks/commit-message.sh --profile product "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
 
 # GIT_DEPTH: 0 (above) gives the changed paths, so the gate can reject an artifact change (epics/**)
 # riding a non-review source branch past the Shape review with a plain code title/template.
-yad-hub-pr-title:
-  extends: .yad_hub_mr_only
+yad-product-pr-title:
+  extends: .yad_product_mr_only
   needs: []
   script:
     - changed="$(mktemp)"; git -c core.quotePath=false diff --no-renames --name-only "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD" > "$changed"
-    - bash checks/pr-title.sh --profile hub --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --changed "$changed" "$CI_MERGE_REQUEST_TITLE"
+    - bash checks/pr-title.sh --profile product --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --changed "$changed" "$CI_MERGE_REQUEST_TITLE"
 
-yad-hub-pr-template:
-  extends: .yad_hub_mr_only
+yad-product-pr-template:
+  extends: .yad_product_mr_only
   needs: []
   script:
     - changed="$(mktemp)"; git -c core.quotePath=false diff --no-renames --name-only "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD" > "$changed"
     - body="$(mktemp)"; printf '%s' "$CI_MERGE_REQUEST_DESCRIPTION" > "$body"
-    - bash checks/pr-template.sh --profile hub --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --changed "$changed" "$body"
+    - bash checks/pr-template.sh --profile product --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --changed "$changed" "$body"
 
-# The gate ledger is CI-owned: reject non-bot commits to .sdlc/{state,approvals,comments,hub-prs}.json
+# The gate ledger is CI-owned: reject non-bot commits to .sdlc/{state,approvals,comments,product-prs,hub-prs}.json
 # or reviews/*.md (.sdlc/contract-lock.json is artifact-side and allowed). The one other exception is a
 # brand-new epic's seed, which no CI path can write, so it rides this first review MR (#162).
-yad-hub-ledger-guard:
-  extends: .yad_hub_mr_only
+yad-product-ledger-guard:
+  extends: .yad_product_mr_only
   needs: []
   script:
     - bash checks/ledger-guard.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"

package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml

@@ -9,8 +9,8 @@
 # Needs a CI/CD variable GITLAB_TOKEN (or SDLC_API_TOKEN) with read_api scope — CI_JOB_TOKEN cannot
 # read the commit-signature API. The Product's SDLC_GATE_TOKEN (from the gate-sync wiring) also works:
 # set GITLAB_TOKEN: $SDLC_GATE_TOKEN in the job if you prefer one token.
-# Job name is yad-hub-prefixed so it can coexist with the code-repo fragment in one pipeline.
-yad-hub-verified-commits:
+# Job name is yad-product-prefixed so it can coexist with the code-repo fragment in one pipeline.
+yad-product-verified-commits:
   needs: []
   # Runner selection: set the YAD_RUNNER_TAGS CI/CD variable (e.g. `dind_runner`) to route this
   # docker job on instances whose runners are tag-locked (run_untagged: false) — it lives in

package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs

@@ -0,0 +1,130 @@
+// ledger-guard CURSOR ADAPTER — the same guard, answered in the protocol Cursor requires (E11).
+//
+// Cursor's `preToolUse` is a PERMISSION hook, and its docs are explicit: for a permission hook,
+// "invalid JSON or a response that doesn't match the hook's schema blocks the action". Empty stdout is
+// invalid JSON. The plain `ledger-guard.mjs` prints nothing when it allows — so wiring it directly
+// would have blocked EVERY file write in a verified project, which is the exact opposite of this
+// guard's fail-open design.
+//
+// This wrapper guarantees one thing: a permission answer on stdout, always, whatever happens below.
+//
+//   allow   {"permission":"allow"}   exit 0
+//   deny    {"permission":"deny","user_message":"<reason>","agent_message":"<reason>"}   exit 0
+//
+// A deny exits 0 because the JSON is the authoritative answer and exit 0 is what tells Cursor to read
+// it; exit 2 blocks too, but is documented as the code for "no JSON to read" and would discard the
+// reason — and naming the command that owns the transition is the whole point of speaking at edit time.
+//
+// A NODE SCRIPT, NOT A SHELL SCRIPT (E113). On Windows Cursor starts hooks through PowerShell, which
+// cannot run a `.sh` file at all. The entry is `node hooks/ledger-guard-cursor.mjs`: a relative path,
+// because Cursor documents that a project hook runs from the project root.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ALLOW = '{"permission":"allow"}';
+const allow = () => { process.stdout.write(`${ALLOW}\n`); process.exit(0); };
+
+// ---- yad-resolve (the same block in every hooks/*.mjs; a test keeps the copies identical) ----------
+// The Product root is this script's grandparent — `<product>/hooks/<script>.mjs` — found from the
+// script's OWN location, never from the harness's working directory or its project-root variable
+// (whose form on Windows, `C:\…` or `/c/…`, no harness documents). `realpathSync` so a script reached
+// through a symbolic link still finds its own Product.
+const PRODUCT_ROOT = path.dirname(path.dirname(fs.realpathSync(fileURLToPath(import.meta.url))));
+const IS_WINDOWS = process.platform === 'win32';
+
+// A command found on PATH, or null. On Windows the npm launchers are `.cmd` files.
+function onPath(name) {
+  const exts = IS_WINDOWS ? ['.cmd', '.exe', ''] : [''];
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const full = path.join(dir, name + ext);
+      try { if (fs.statSync(full).isFile()) return full; } catch { /* not here */ }
+    }
+  }
+  return null;
+}
+
+// Windows cannot start a `.cmd` launcher without a shell (Node refuses since 18.20.2), so those run
+// through one, each word in double quotes. A Windows path cannot hold a `"`, so the quoting is whole.
+const quoteForCmd = (word) => `"${String(word).replace(/"/g, '')}"`;
+
+// How to run `yad`, cheapest and most specific first: an explicit override, then the copy installed in
+// this Product, then `yad` on PATH, then a network-free npx. `--no-install` matters — a hook runs on
+// every tool call and must never pause an agent to download a package. Returns
+// `{ file, args, shell }` or null.
+function resolveYad() {
+  // YAD_BIN is commonly an interpreter plus a script ("node /path/to/yad.mjs"). Split on spaces, with a
+  // double-quoted word kept whole — Node on Windows usually lives under `C:\Program Files\`.
+  const override = [...(process.env.YAD_BIN || '').matchAll(/"([^"]*)"|(\S+)/g)].map((m) => m[1] ?? m[2]).filter(Boolean);
+  if (override.length) {
+    const [file, ...args] = override;
+    return { file, args, shell: IS_WINDOWS && /\.(cmd|bat)$/i.test(file) };
+  }
+  const local = path.join(PRODUCT_ROOT, 'node_modules', 'yadflow', 'bin', 'yad.mjs');
+  if (fs.existsSync(local)) return { file: process.execPath, args: [local], shell: false };
+  const yad = onPath('yad');
+  if (yad) {
+    if (!IS_WINDOWS || !/\.(cmd|bat)$/i.test(yad)) return { file: yad, args: [], shell: false };
+    // An npm global install puts the package beside its launcher: run the script with this Node
+    // rather than through a shell whenever it is there.
+    const script = path.join(path.dirname(yad), 'node_modules', 'yadflow', 'bin', 'yad.mjs');
+    if (fs.existsSync(script)) return { file: process.execPath, args: [script], shell: false };
+    return { file: yad, args: [], shell: true };
+  }
+  const npx = onPath('npx');
+  if (npx) return { file: npx, args: ['--no-install', 'yadflow'], shell: IS_WINDOWS && /\.(cmd|bat)$/i.test(npx) };
+  return null;
+}
+
+// Run the resolved `yad` with `args` appended. `options` go to spawnSync.
+function runYad(yad, args, options) {
+  const all = [...yad.args, ...args];
+  if (yad.shell) return spawnSync([yad.file, ...all].map(quoteForCmd).join(' '), { ...options, shell: true, windowsHide: true });
+  return spawnSync(yad.file, all, { ...options, windowsHide: true });
+}
+// ---- end yad-resolve ---------------------------------------------------------------------------------
+
+// Every failure below this line resolves to ALLOW, because this guard fails open by design and CI is
+// what fails closed. A wrapper that blocked when it could not reach `yad` would stop an agent editing
+// anything at all the moment an install went sideways.
+const yad = resolveYad();
+if (!yad) {
+  process.stderr.write(`  • yad hook: no \`yad\` on PATH and none installed in ${PRODUCT_ROOT} — allowing (install yadflow to re-arm the ledger guard)\n`);
+  allow();
+}
+
+// stdout is CAPTURED (the JSON verdict); stdin (the tool-call payload) and stderr (Cursor's log) are
+// the harness's own.
+const r = runYad(yad, ['hook', 'ledger-guard', '--format', 'cursor'], { stdio: ['inherit', 'pipe', 'inherit'], encoding: 'utf8' });
+
+// THE VERDICT IS THE LAST NON-EMPTY LINE, not the whole of stdout, and it is recognised by containing
+// a `"permission"` key rather than by starting with one. `yad`'s own top-level failure handler prints
+// to STDOUT, so a usage error or a crash banner can land in front of the JSON; a prefix test would then
+// fail to recognise our own deny and fall through to the allow below. And a containment test does not
+// care what order the JSON's properties are in.
+const lines = String(r.stdout || '').split(/\r?\n/).filter((l) => l.trim());
+const verdict = lines.length ? lines[lines.length - 1] : '';
+if (verdict.includes('"permission"')) { process.stdout.write(`${verdict}\n`); process.exit(0); }
+
+// EXIT 2 IS A DENY, even with nothing on stdout — and this branch is reached in a real, ordinary case.
+// The Product's own `node_modules/yadflow` comes BEFORE `PATH`, so a project pinned to a yadflow older
+// than `--format` parses the flag, ignores it, and answers in the exit protocol: exit 2, empty stdout.
+// The message is FIXED: the reason the older `yad` printed has already gone to stderr, where Cursor
+// logs it.
+if (r.status === 2) {
+  process.stdout.write(`${JSON.stringify({
+    permission: 'deny',
+    user_message: 'yad: this edit touches CI-owned gate state.',
+    agent_message: 'This edit touches CI-owned gate state, which CI is the sole writer of. Do not edit the ledger by hand: use `yad gate open` for the transition, and commit only the artifact. The installed yadflow is older than this hook, so the full reason is in the hook log rather than here — `yad doctor` will name the version gap.',
+  })}\n`);
+  process.exit(0);
+}
+
+if (r.status !== 0) {
+  const why = r.error ? r.error.message : `exited ${r.status ?? r.signal}`;
+  process.stderr.write(`  • yad hook: \`yad hook ledger-guard\` ${why} — allowing (run \`yad doctor\` to check the install)\n`);
+}
+allow();