yadflow 3.18.1 → 4.0.0-next.1

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

@@ -1,24 +1,23 @@
 #!/usr/bin/env bash
 # verified-commits gate.
-# Every commit in the range under review must (1) carry a signature the PLATFORM marks as verified
-# (the GitHub/GitLab "Verified" badge — proves the commit was signed by a key registered to the
-# account that owns the author email) and (2) be AUTHORED by a known identity: the author email must
-# appear in the .sdlc/verified-authors allowlist (generated by `yad check --fix` from the hub
-# roster's `email` fields + hub.json `verified_authors`). Unsigned commits and commits from unknown
-# authors do not reach merge — on the product hub and on every connected repo alike.
+# Every commit in the range under review must carry a signature the PLATFORM marks as verified (the
+# GitHub/GitLab "Verified" badge — proves the commit was signed by a key registered to the account that
+# owns the author email). Unsigned commits do not reach merge — on the Product and on every connected
+# repo alike.
 #
-# Only the AUTHOR email is checked against the allowlist: platform-generated merge/squash/update
-# commits set the platform itself as the committer (e.g. noreply@github.com), and their integrity is
-# covered by the signature check (the platform signs them).
+# There is no author allowlist. It used to be `.sdlc/verified-authors`, generated from the Product
+# roster's emails; yadflow removed the roster (E62) and keeps no list of people. Who may author a commit
+# is who has write access to the repository — the platform's own answer, which never goes stale — and
+# the signature proves which platform account made the commit. A `.sdlc/verified-authors` file an older
+# release generated is no longer read, and the gate says so when it finds one.
 #
 # Merge-commit signature exemption: a merge that introduces NO content of its own (its combined diff
 # is empty — no conflict-resolution / evil-merge hunks) is signature-waived, because every change it
-# carries already lives in its individually author+signature-checked parents. This unblocks self-hosted
+# carries already lives in its individually signature-checked parents. This unblocks self-hosted
 # GitLab, which does not sign UI-created merge commits (the signature API returns 404). A merge that
 # DOES introduce content of its own still requires a verified signature (fail-closed).
 #
 # Degradation is explicit, never silent:
-#   - no allowlist file        -> author check SKIPPED with a warning (configure emails, re-wire)
 #   - no GitHub/GitLab remote  -> signature check SKIPPED with a warning (no platform, no badge)
 #   - platform API unreachable -> FAIL closed (a security gate must not pass on a broken check)
 #
@@ -64,13 +63,10 @@ if [ -z "$commits" ]; then
   exit 0
 fi
 
-# ---- author allowlist (one email per line; # comments; case-insensitive) -------------------------
-ALLOWLIST="${SDLC_VERIFIED_AUTHORS:-.sdlc/verified-authors}"
-authors_on=0
-if [ -f "$ALLOWLIST" ]; then
-  authors_on=1
-else
-  echo "WARN [verified-commits]: ${ALLOWLIST} not found — author allowlist NOT enforced. Add 'email' to the hub roster (or hub.json 'verified_authors'), then run \`yad check --fix\`."
+# ---- the author allowlist is gone (E62) ------------------------------------------------------------
+# Said out loud when an older one is still on disk, so nobody edits it believing it decides something.
+if [ -f .sdlc/verified-authors ]; then
+  echo "note [verified-commits]: .sdlc/verified-authors is no longer read — write access to the repo decides who can author; the signature is still required."
 fi
 
 # ---- platform for the signature check (override with SDLC_PLATFORM=github|gitlab|none) -----------
@@ -120,7 +116,7 @@ signature_verified() {
 # 0 when a merge commit introduced NO content of its own. The combined diff (--cc) lists only hunks
 # that differ from ALL parents, so empty output means every change lives in an individually-checked
 # parent — there is no conflict-resolution or evil-merge content unique to the merge commit, hence
-# nothing an unverified author could smuggle in past the per-parent author+signature checks.
+# nothing an unsigned change could smuggle in past the per-parent signature checks.
 merge_introduces_no_content() {
   # `local` on its own line: `local out=$(...)` would mask the substitution's exit status (local
   # always returns 0). A git error (e.g. a parent tree missing in a shallow clone) must fail closed —
@@ -134,37 +130,15 @@ rc=0
 while IFS= read -r sha; do
   [ -z "$sha" ] && continue
   short="$(git log -1 --format=%h "$sha")"
-  author="$(git log -1 --format=%ae "$sha" | tr '[:upper:]' '[:lower:]')"
-  # The gate-sync bot is a machine identity, not a roster human — waive the allowlist for it. Its
-  # commits are still held to the SIGNATURE check below, so a contributor cannot spoof the bot author
-  # to dodge the allowlist (a forged-author commit is not platform-Verified). Mirrors how the
-  # platform-committer merge commits are allowlist-exempt but signature-covered.
-  is_bot=0
-  case "${author}|$(git log -1 --format=%an "$sha" | tr '[:upper:]' '[:lower:]')" in *yad-gate-sync*) is_bot=1 ;; esac
 
-  # A merge commit (2+ parents) is authored by whoever pressed "merge" — often a platform noreply
-  # address, not a roster human — while its CONTENT already passed the PR gate suite. Waive the
-  # allowlist for it (like the bot), but STILL require the signature below: a platform merge commit is
-  # Verified, so a locally-forged merge pushed direct-to-default cannot dodge the check. This matters
-  # for the push-on-default yad-update-guard, which (unlike the PR-triggered gates) sees merge commits.
+  # A merge commit (2+ parents) whose content is all in its parents may go unsigned — see
+  # merge_introduces_no_content. Every other commit, merges with content of their own included, needs
+  # the signature: a platform merge commit is Verified, so a locally-forged merge pushed
+  # direct-to-default cannot dodge the check. This matters for the push-on-default yad-update-guard,
+  # which (unlike the PR-triggered gates) sees merge commits.
   is_merge=0
   [ "$(git log -1 --format=%P "$sha" | wc -w | tr -d '[:space:]')" -ge 2 ] && is_merge=1
 
-  if [ "$authors_on" = 1 ] && [ "$is_bot" = 0 ] && [ "$is_merge" = 0 ]; then
-    # tolerate CRLF / stray surrounding whitespace in a hand-edited allowlist
-    if grep -vE '^[[:space:]]*(#|$)' "$ALLOWLIST" | tr -d '\r' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' \
-        | tr '[:upper:]' '[:lower:]' | grep -qxF "$author"; then
-      echo "PASS [verified-commits]: ${short} author <${author}> is a known identity"
-    else
-      echo "FAIL [verified-commits]: ${short} author <${author}> is not in ${ALLOWLIST} — unverified user."
-      rc=1
-    fi
-  elif [ "$is_bot" = 1 ]; then
-    echo "PASS [verified-commits]: ${short} gate-sync bot — allowlist waived (signature still required)"
-  elif [ "$is_merge" = 1 ]; then
-    echo "PASS [verified-commits]: ${short} merge commit — allowlist waived (signature still required)"
-  fi
-
   if [ -n "$platform" ]; then
     if signature_verified "$sha"; then
       echo "PASS [verified-commits]: ${short} signature verified by ${platform}"

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

@@ -1,5 +1,5 @@
 # yad-managed: yad-checks
-# SDLC check gates (Phase 3 build plan §C). The three gates run on every PR and must pass before
+# SDLC check gates (Phase 3 build plan §C). The gates below run on every PR and must pass before
 # merge. They are CI-agnostic bash in checks/ — this workflow just invokes them with the PR base.
 # This workflow file is OWNED by yad-checks (the marker on line 1 identifies it). It runs
 # independently of any other workflow in .github/workflows/, so wiring never edits a foreign workflow.
@@ -29,17 +29,49 @@ jobs:
         with: { fetch-depth: 0 }
       - 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
+  # approver count read from the base branch's map. The script always exits 0: the count is reported,
+  # not enforced, and a stale map never blocks a merge.
+  risk-map:
+    runs-on: ubuntu-latest
+    if: github.event.action != 'edited'
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - run: bash checks/risk-map-check.sh "origin/${{ github.base_ref }}"
+
   build-test-lint:
     runs-on: ubuntu-latest
     if: github.event.action != 'edited'
     env:
       YAD_TEST_MAX_WORKERS: "2" # cap jest/vitest test workers in CI; ignored by other runners
+      YAD_NODE_VERSION: ${{ vars.YAD_NODE_VERSION || '22' }} # repo variable; a current 20, 22 or 24 line (Node 25+ has no Corepack)
+      NX_BASE: ${{ github.event.pull_request.base.sha }}
+      NX_HEAD: ${{ github.event.pull_request.head.sha }}
+      COREPACK_HOME: ${{ github.workspace }}/.corepack-cache # pinned-manager downloads, cached below
     steps:
       - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
+        with:
+          fetch-depth: 0
+          filter: blob:none
       - uses: actions/setup-node@v4
-        with: { node-version: "20", cache: "npm" }
-      - run: npm ci # install deps so the real lint/build/test toolchain can run (mirrors the GitLab template)
+        with:
+          node-version: ${{ env.YAD_NODE_VERSION }}
+      # Dependency cache for either manager: npm's ~/.npm, pnpm's content-addressable store, and the
+      # Corepack home where `corepack prepare` keeps the pinned manager (otherwise re-downloaded from
+      # the registry on every job, even when the dependency cache hits). Keyed on the lockfiles AND
+      # 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
+        with:
+          path: |
+            ~/.npm
+            ~/.local/share/pnpm/store
+            ${{ env.COREPACK_HOME }}
+          key: yad-deps-${{ runner.os }}-node${{ env.YAD_NODE_VERSION }}-${{ hashFiles('package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'package.json') }}
+          restore-keys: yad-deps-${{ runner.os }}-node${{ env.YAD_NODE_VERSION }}-
+      - run: bash checks/install-deps.sh
       - run: bash checks/build-test-lint.sh
 
   # Phase 6 — feature-thread gates. lineage-check: the change links a real threaded epic. epic-open:
@@ -99,7 +131,7 @@ jobs:
           body="$(mktemp)"; printf '%s' "$PR_BODY" > "$body"
           bash checks/pr-template.sh --profile code "$body"
 
-  # No unverified commits from unverified users: platform-Verified signature + allowlisted author.
+  # No unverified commits: a platform-Verified signature on every commit (write access decides who authors).
   # Reads the commit range, not the title/body — skip it on a bare `edited` event.
   verified-commits:
     runs-on: ubuntu-latest

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

@@ -1,8 +1,8 @@
 # yad-managed: yad-checks
-# Pattern gates for the PRODUCT HUB. They run with `--profile hub` and split by head branch:
-#   review/EP-* PRs are front-half artifact-review vehicles — a `review: <artifact> (EP-<slug>)` title
-#     and the hub artifact-review template body.
-#   every other PR is a tooling/code change to the hub itself — a Conventional-Commits title and the
+# Pattern gates for the PRODUCT. They run with `--profile hub` 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.
@@ -27,7 +27,7 @@ jobs:
 
   # 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
-  # change (epics/**) riding a non-review head past the front-half review with a plain code title.
+  # change (epics/**) riding a non-review head past the Shape review with a plain code title.
   pr-title:
     runs-on: ubuntu-latest
     env:

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

@@ -1,14 +1,13 @@
 # yad-managed: yad-checks
 # yad-update-guard — integrity gate for DIRECT pushes to the default branch.
 #
-# `yad update --push` commits the applied SDLC drift (skills, gate scripts, CI wiring, verified-
-# authors) and pushes it straight to the default branch with NO pull request — so the pull_request
+# `yad update --push` commits the applied SDLC drift (skills, gate scripts, CI wiring) and pushes it
+# straight to the default branch with NO pull request — so the pull_request
 # gate suite never fires. This workflow is the "skipped from CI EXCEPT verified-commits + the pattern
 # gate" contract: on every push to the default branch it runs ONLY those two gates over the pushed
 # range. It is not scoped to yad-update commits on purpose — ANY direct-to-main commit (a hotfix, a
 # force-push) then gets signature + subject-format checked, which is a strictly-good invariant. A
-# normal PR merge sails through: a GitHub merge/squash commit is platform-Verified, verified-commits.sh
-# waives the allowlist for merge commits (whose author is whoever clicked merge), and commit-message.sh
+# normal PR merge sails through: a GitHub merge/squash commit is platform-Verified, and commit-message.sh
 # skips merges. CAVEAT: a *rebase-merge* recreates the PR commits WITHOUT GitHub's signature, so they
 # lose the Verified badge and fail the signature check on the direct push — teams using rebase-merge
 # should sign their commits or not wire this guard.

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

@@ -1,8 +1,8 @@
 # yad-managed: yad-checks
-# verified-commits gate for the PRODUCT HUB: every PR (including the front-half review/EP-* PRs)
-# must contain only commits whose signature the platform marks Verified AND whose author email is a
-# known identity (.sdlc/verified-authors — generated by `yad check --fix` from the hub roster).
-# Standalone workflow so it never collides with the hub-flavored yad-checks workflow.
+# verified-commits gate for the PRODUCT: every PR (including the Shape review/EP-* PRs)
+# must contain only commits whose signature the platform marks Verified. Who may author them is who has
+# write access to the repo — yadflow keeps no author list.
+# Standalone workflow so it never collides with the Product-flavored yad-checks workflow.
 name: yad-verified-commits
 on:
   pull_request:

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

@@ -4,7 +4,7 @@
 stages: [spec-link, contract-check, build-test-lint, verified-commits]
 
 default:
-  image: node:20
+  image: node:${YAD_NODE_VERSION}
 
 .mr_only:
   rules:
@@ -12,6 +12,9 @@ default:
 
 variables:
   GIT_DEPTH: "0"   # full history so the gates can diff against the target branch
+  YAD_NODE_VERSION: "22" # override with a project/group CI variable (a current 20, 22 or 24 line; Node 25+ has no Corepack)
+  NX_BASE: $CI_MERGE_REQUEST_DIFF_BASE_SHA
+  NX_HEAD: $CI_COMMIT_SHA
 
 spec-link:
   stage: spec-link
@@ -28,7 +31,10 @@ contract-check:
 build-test-lint:
   stage: build-test-lint
   extends: .mr_only
+  variables:
+    YAD_TEST_MAX_WORKERS: "2" # cap jest/vitest test workers in CI; ignored by other runners
   script:
+    - bash checks/install-deps.sh
     - bash checks/build-test-lint.sh
 
 # Needs a CI/CD variable GITLAB_TOKEN (or SDLC_API_TOKEN) with read_api scope — CI_JOB_TOKEN cannot

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

@@ -14,10 +14,19 @@
 # top-level `default:` merges into the HOST root pipeline; if the host already sets a top-level
 # `image:`, GitLab rejects the whole config ("image is defined in top-level and 'default:' entry").
 # Putting them on the anchor scopes them to the gate jobs (which all `extends: .sdlc_mr_only`) and
-# never touches the host root.
+# never touches the host root. The same goes for the gate jobs' own variables (`YAD_NODE_VERSION`,
+# `NX_BASE`, `NX_HEAD`): an included top-level `variables:` merges into the host's globals, where a
+# generic name like NX_BASE can collide with one the host already computes for its own Nx jobs.
+# Only `GIT_DEPTH` stays global — the gates need the full history and a host that sets its own wins.
 
 .sdlc_mr_only:
-  image: node:20
+  image: node:${YAD_NODE_VERSION}
+  variables:
+    # A project/group CI/CD variable overrides a YAML value, so YAD_NODE_VERSION can be changed in
+    # project settings without editing the managed fragment (a current 20, 22 or 24 line; Node 25+ has no Corepack).
+    YAD_NODE_VERSION: "22"
+    NX_BASE: $CI_MERGE_REQUEST_DIFF_BASE_SHA
+    NX_HEAD: $CI_COMMIT_SHA
   # Runner selection. These jobs need a docker/dind executor; on instances whose runners are all
   # tag-locked (run_untagged: false) an untagged image job never starts. Set the YAD_RUNNER_TAGS
   # CI/CD variable (Settings → CI/CD → Variables, e.g. `dind_runner`) to route them — it lives in
@@ -44,13 +53,22 @@ yad-contract-check:
   script:
     - 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
+# approver count read from the base branch's map. It never fails the pipeline (the count is reported,
+# not enforced), so the job needs no allow_failure.
+yad-risk-map:
+  extends: .sdlc_mr_only
+  needs: []
+  script:
+    - bash checks/risk-map-check.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+
 yad-build-test-lint:
   extends: .sdlc_mr_only
   needs: []
   variables:
     YAD_TEST_MAX_WORKERS: "2" # cap jest/vitest test workers in CI; ignored by other runners
   script:
-    - npm ci
+    - bash checks/install-deps.sh
     - bash checks/build-test-lint.sh
 
 # Phase 6 — feature-thread gates (lineage / seal / hotfix-debt). Build on spec-link's story->epic
@@ -93,7 +111,7 @@ yad-pr-template:
     - body="$(mktemp)"; printf '%s' "$CI_MERGE_REQUEST_DESCRIPTION" > "$body"
     - bash checks/pr-template.sh --profile code "$body"
 
-# No unverified commits from unverified users: platform-Verified signature + allowlisted author.
+# No unverified commits: a platform-Verified signature on every commit (write access decides who authors).
 # Needs a CI/CD variable GITLAB_TOKEN (or SDLC_API_TOKEN) with read_api scope — CI_JOB_TOKEN cannot
 # read the commit-signature API. Without it the job FAILS closed with guidance.
 yad-verified-commits:

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

@@ -1,11 +1,11 @@
 # yad-managed-include: yad-checks
-# Pattern gates for the PRODUCT HUB, as an INCLUDABLE fragment. Pulled into the hub's root
+# 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 front-half artifact-
-# review vehicles (a `review: <artifact> (EP-<slug>)` title + the hub artifact-review template body);
-# every other MR is a tooling/code change to the hub itself and follows the code convention (a
+# MRs run with `--profile hub` 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
@@ -28,7 +28,7 @@ yad-hub-commit-message:
     - bash checks/commit-message.sh --profile hub "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 front-half review with a plain code title/template.
+# 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
   needs: []

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

@@ -1,13 +1,13 @@
 # yad-managed-include: yad-checks
-# verified-commits gate for the PRODUCT HUB, as an INCLUDABLE fragment. Pulled into the hub's root
+# verified-commits gate for the PRODUCT, as an INCLUDABLE fragment. Pulled into the Product's root
 # .gitlab-ci.yml via:
 #   include:
 #     - local: '.gitlab/ci/yad-verified-commits.yml'
-# Every MR (including the front-half review/EP-* MRs) must contain only commits whose signature the
-# platform marks Verified AND whose author email is a known identity (.sdlc/verified-authors).
+# Every MR (including the Shape review/EP-* MRs) must contain only commits whose signature the
+# platform marks Verified. Who may author them is who has write access to the repo — no author list.
 #
 # 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 hub's SDLC_GATE_TOKEN (from the gate-sync wiring) also works:
+# 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:

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

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# 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.sh` 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.
+#
+# It takes NO arguments, deliberately. Cursor's `hooks.json` holds one command STRING and does not
+# document whether it is run through a shell, so a command with a flag in it might never be split into
+# program and argument — a command not found, silently, on every call.
+set -uo pipefail
+
+# `CDPATH=` is load-bearing, and the Cursor entry is what makes it so: that entry invokes the script
+# by a RELATIVE path, so `${BASH_SOURCE[0]}` is relative and `cd` consults $CDPATH before the current
+# directory. An exported CDPATH in a login profile — an ordinary thing to have, and inherited by the
+# harness — would resolve `hooks` to some other tree entirely, and the guard would fail open on every
+# write for as long as that profile lived.
+#
+# The loop resolves a symlinked SCRIPT, which `cd -P` does not: `-P` resolves the directory path, and
+# a script reached through a link in another directory would otherwise look for its sibling beside the
+# LINK and not find it. `readlink` without `-f` because `-f` is not portable to macOS.
+_src="${BASH_SOURCE[0]}"
+while [ -L "$_src" ]; do
+  _dir="$(CDPATH= cd -P -- "$(dirname -- "$_src")" && pwd)"
+  _src="$(readlink -- "$_src")"
+  case "$_src" in /*) ;; *) _src="$_dir/$_src" ;; esac
+done
+HOOK_DIR="$(CDPATH= cd -P -- "$(dirname -- "$_src")" && pwd)"
+ALLOW='{"permission":"allow"}'
+
+# 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.
+if [ ! -x "$HOOK_DIR/ledger-guard.sh" ]; then
+  echo "  • yad hook: $HOOK_DIR/ledger-guard.sh is missing or not executable — allowing (run \`yad check --fix\`)" >&2
+  echo "$ALLOW"
+  exit 0
+fi
+
+# stdout is CAPTURED (the JSON verdict), stderr is not (it flows through to Cursor's log). stdin is
+# inherited by the command substitution, so the tool-call payload still reaches the guard.
+raw="$("$HOOK_DIR/ledger-guard.sh" --format cursor)"
+rc=$?
+
+# 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.
+#
+# Both halves of that matter. `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, turning a real refusal into a permitted write with nothing
+# on stderr to say so. And a containment test does not care what order the JSON's properties are in,
+# so the deny answer's shape on the other side of this language boundary is not silently load-bearing.
+verdict="$(printf '%s\n' "$raw" | awk 'NF { line = $0 } END { print line }')"
+
+# `ledger-guard.sh` has its own fail-open branches that exit 0 with EMPTY stdout — no `yad` on PATH,
+# an install it cannot resolve — and each one of those would otherwise reach Cursor as invalid JSON
+# and block the write.
+case "$verdict" in
+  *'"permission"'*) echo "$verdict"; exit 0 ;;
+esac
+
+# EXIT 2 IS A DENY, even with nothing on stdout — and this branch is reached in a real, ordinary case.
+# `ledger-guard.sh` resolves `yad` from the Product's own `node_modules/yadflow` 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. Falling through to the generic allow below would turn a real
+# refusal into a permitted write, and print "exited 2 — allowing" while doing it.
+#
+# The message is a FIXED literal with nothing interpolated. The reason the older `yad` printed has
+# already gone to stderr, where Cursor logs it; escaping arbitrary multi-line text into JSON in bash
+# is exactly the sort of thing that produces an off-schema response, and there is no need to risk it.
+if [ "$rc" -eq 2 ]; then
+  echo '{"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."}'
+  exit 0
+fi
+
+if [ "$rc" -ne 0 ]; then
+  echo "  • yad hook: ledger-guard.sh exited $rc — allowing (run \`yad doctor\` to check the install)" >&2
+fi
+echo "$ALLOW"
+exit 0

package/skills/yad-checks/templates/hooks/ledger-guard.sh

@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 # ledger-guard HARNESS HOOK — the local half of the CI gate of the same name (#171).
 #
-# The gate ledger is CI-owned in bridge mode: `checks/ledger-guard.sh` rejects any non-bot commit
-# that changes `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or `epics/*/reviews/*.md`.
+# The gate ledger is CI-owned in verified mode: `checks/ledger-guard.sh` rejects any non-bot commit
+# that changes `epics/*/.sdlc/{state,approvals,comments,product-prs,hub-prs}.json` or `epics/*/reviews/*.md`,
+# and the same files for the Foundation in `foundation/.sdlc/` and `foundation/reviews/` (E75).
 # This hook says so at the moment an agent tries the edit, instead of twenty minutes later in a
 # failed pipeline, and names the command that owns the transition (`yad gate open`).
 #
@@ -14,21 +15,51 @@
 #   exit 0  allow
 #   exit 2  deny, reason on stderr
 #
-# Wired for Claude Code as a `PreToolUse` hook in `.claude/settings.json` (`yad check --fix` writes
-# that entry). Any harness that can run a command and read those two exit codes can use it.
+# Wired by `yad check --fix` for every harness that can refuse a write BEFORE it lands:
+#   Claude Code  a `PreToolUse` hook in `.claude/settings.json`, pointing straight at THIS script
+#   Cursor       a `preToolUse` hook in `.cursor/hooks.json`, pointing at `ledger-guard-cursor.sh`
+#
+# DO NOT WIRE THIS SCRIPT INTO CURSOR DIRECTLY, and check the same thing before wiring it into any
+# other harness by hand. Cursor's `preToolUse` is a PERMISSION hook: it wants a JSON verdict on
+# stdout, and treats an empty or off-schema answer as a refusal. This script prints NOTHING when it
+# allows — so wired there directly it would block every file write in the project, which is the
+# opposite of the fail-open stance below. `ledger-guard-cursor.sh` exists to speak that protocol.
+#
+# A harness that reads the EXIT CODE can use this script as it stands. A hook that only fires AFTER
+# the write — Cursor's `afterFileEdit`, for one — is deliberately not used: it could report the edit
+# but never refuse it, and reporting is what the CI gate already does.
+#
+# The project root is resolved from this script's own location below, so it does not matter which
+# variable the harness sets ($CLAUDE_PROJECT_DIR, $CURSOR_PROJECT_DIR) or where it runs the command
+# from; those variables appear only in the wiring, to point at this file.
 #
 # FAIL-OPEN: if no `yad` can be found, this ALLOWS and says why on stderr. A guardrail that blocked
 # every edit the moment an install went sideways would be worse than the problem. The CI gate fails
 # CLOSED and is what actually protects the ledger.
 set -uo pipefail
 
-# The hub root is this script's grandparent — hooks/ledger-guard.sh — so the resolution below does
+# The Product root is this script's grandparent — hooks/ledger-guard.sh — so the resolution below does
 # not depend on the harness's working directory.
-HOOK_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+# `CDPATH=` is load-bearing, and the Cursor entry is what makes it so: that entry invokes the script
+# by a RELATIVE path, so `${BASH_SOURCE[0]}` is relative and `cd` consults $CDPATH before the current
+# directory. An exported CDPATH in a login profile — an ordinary thing to have, and inherited by the
+# harness — would resolve `hooks` to some other tree entirely, and the guard would fail open on every
+# write for as long as that profile lived.
+#
+# The loop resolves a symlinked SCRIPT, which `cd -P` does not: `-P` resolves the directory path, and
+# a script reached through a link in another directory would otherwise look for its sibling beside the
+# LINK and not find it. `readlink` without `-f` because `-f` is not portable to macOS.
+_src="${BASH_SOURCE[0]}"
+while [ -L "$_src" ]; do
+  _dir="$(CDPATH= cd -P -- "$(dirname -- "$_src")" && pwd)"
+  _src="$(readlink -- "$_src")"
+  case "$_src" in /*) ;; *) _src="$_dir/$_src" ;; esac
+done
+HOOK_DIR="$(CDPATH= cd -P -- "$(dirname -- "$_src")" && pwd)"
 HUB_ROOT="$(dirname -- "$HOOK_DIR")"
 
 # Resolution order, cheapest and most specific first: an explicit override, then the copy installed
-# in this hub, then whatever is on PATH, then a network-free npx. `--no-install` matters — a hook
+# in this Product, then whatever is 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.
 CMD=()
 _yad_bin="${YAD_BIN:-}"

package/skills/yad-commit/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: yad-commit
-description: 'Build-half helper of the gated SDLC. Commit ONE staged atomic change by the conventions — a Conventional-Commits subject, the fixed trailer order (Task → Contract-Change, plus an OPTIONAL Co-Authored-By), and an atomic-file guard (≤3 files). By default the commit carries NO AI footer: the human git author owns it, and a Co-Authored-By trailer is added ONLY when --ai <id> is explicitly passed (claude|copilot|cursor|coderabbit; default none = human-only). The flag is the sole switch — never add the footer on the AI''s own initiative. Drives the zero-dependency `yad commit` CLI; never auto-advances. Use when the user says "commit this", "commit by convention", or "make an atomic commit".'
+description: 'Build helper of the gated SDLC. Commit ONE staged atomic change by the conventions — a Conventional-Commits subject, the fixed trailer order (Task → Contract-Change, plus an OPTIONAL Co-Authored-By), and an atomic-file guard (≤3 files). By default the commit carries NO AI footer: the human git author owns it, and a Co-Authored-By trailer is added ONLY when --ai <id> is explicitly passed (claude|copilot|cursor|coderabbit; default none = human-only). The flag is the sole switch — never add the footer on the AI''s own initiative. Drives the zero-dependency `yad commit` CLI; never auto-advances. Use when the user says "commit this", "commit by convention", or "make an atomic commit".'
 ---
 
-# SDLC — Commit by Convention (build-half helper)
+# SDLC — Commit by Convention (Build helper)
 
 **Goal:** Turn ONE staged atomic change into a single commit that satisfies the project conventions
 (`CONTRIBUTING.md` / `config.yaml` `build`): a Conventional-Commits subject, the fixed trailer order
@@ -14,7 +14,7 @@ and `yad-ship` use. It **never auto-advances**; it just commits.
 ## Conventions
 
 - Run **inside the repo holding the staged change** — a code repo under
-  `{project-root}/demo-repos/<repo>/`, or the product hub itself. Use absolute paths.
+  `{project-root}/demo-repos/<repo>/`, or the Product itself. Use absolute paths.
 - **Stage first.** Only the staged (`git add`) atomic change is committed. The guard refuses more than
   `ATOMIC_FILE_LIMIT` (3) staged files unless `--force` — split the change instead.
 - **Subject** — `<type>: <lowercase imperative description, no trailing period>`; types are
@@ -22,8 +22,8 @@ and `yad-ship` use. It **never auto-advances**; it just commits.
 - **Task trailer** — required on a code repo (anchors the `spec-link` + `commit-message` gates). Given
   with `--task` (a `<story>-T<NN>` id — an explicit value is validated against the `spec-link`
   contract, so a malformed id like a bare `EP-x-S01` fails locally instead of after a push), else
-  derived from the branch (`feat/<story>-<task>-…`). Hub commits are not
-  task-scoped, so the trailer is optional there — a missing-Task warning is informational on the hub
+  derived from the branch (`feat/<story>-<task>-…`). Product commits are not
+  task-scoped, so the trailer is optional there — a missing-Task warning is informational on the Product
   (`spec-link` is a code-repo gate) and only flags a real gate failure in a code repo.
 - **Contract-Change trailer** — `--contract-change` only when the diff touches the locked contract
   surface; it routes the change back to the architecture gate.
@@ -70,6 +70,6 @@ the architecture gate. To also open the PR/MR in the same step, use `yad-ship`.
 
 ## Reference
 - Branch/commit conventions + the file-boundary rule: `../yad-implement/references/implement-conventions.md`.
-- The full convention text: `CONTRIBUTING.md`; the config: `skills/sdlc/config.yaml` `build`.
+- The full convention text: `CONTRIBUTING.md`; the config: `.sdlc/config.yaml` `build`.
 - The gate that enforces the subject pattern: `../yad-checks/references/check-gates.md` (`commit-message`).
 - Open the PR/MR after committing: `../yad-open-pr/SKILL.md`; both at once: `../yad-ship/SKILL.md`.

package/skills/yad-connect-design/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: yad-connect-design
-description: 'Connects a design tool (Figma, or another tool — pluggable) to the product hub so the UI design step can materialize the full feature design (mobile screens / web pages) inside it, not just Markdown. Registers the tool into the project-wide .sdlc/design.json (local-user / MCP-session auth, no stored tokens), detecting whether a design-tool MCP is available and degrading to markdown-only when it is not. Run at setup or any time the design tool changes. Reusable, idempotent, refreshable. Use when the user says "connect Figma", "connect a design tool", "refresh the design connection", or "list the design connection".'
+description: 'Connects a design tool (Figma, or another tool — pluggable) to the Product so the UI design step can materialize the full feature design (mobile screens / web pages) inside it, not just Markdown. Registers the tool into the project-wide .sdlc/design.json (local-user / MCP-session auth, no stored tokens), detecting whether a design-tool MCP is available and degrading to markdown-only when it is not. Run at setup or any time the design tool changes. Reusable, idempotent, refreshable. Use when the user says "connect Figma", "connect a design tool", "refresh the design connection", or "list the design connection".'
 ---
 
 # SDLC — Connect a Design Tool (make the UI step design-tool aware)
 
 **Goal:** Let the UI design step (`yad-ui`) produce the **actual feature design** — the mobile screens
 and/or web pages — inside a design tool such as **Figma**, alongside the Markdown artifacts
-(`ui-design.md` / `DESIGN.md`). This skill **connects** a design tool to the product hub and records
+(`ui-design.md` / `DESIGN.md`). This skill **connects** a design tool to the Product and records
 *how* to reach it (the tool, the project/file references, which MCP renders it) — never a credential.
 
-This is **setup/maintenance**, not a gated front state — it never touches `.sdlc/state.json` or any
+This is **setup/maintenance**, not a gated Shape step — it never touches `.sdlc/state.json` or any
 epic's approvals. It only writes the project-wide design registry. `yad-ui` consumes it: when a tool is
 connected and its MCP is available, the `ux-designer` lens **generates** screens into the tool (or
 **links** an existing human-made design and reads it back); when nothing is connected, `yad-ui` runs
@@ -18,7 +18,7 @@ markdown-only exactly as before.
 
 ## Conventions
 
-- `{project-root}` resolves from the project working directory (the **product hub**).
+- `{project-root}` resolves from the project working directory (the **Product**).
 - The integration is **Figma-first but pluggable** (`config.yaml` `design.tools`): a design-tool
   *adapter*, like the GitHub/GitLab platform adapter. Figma is the primary provider; `pencil`
   (the `.pen` web/mobile editor) is a second, write-capable provider; `none` → markdown-only.
@@ -29,7 +29,7 @@ markdown-only exactly as before.
   the sibling of `.sdlc/repos.json` and `.sdlc/hub.json`.
 - Per-epic screen→frame links are written later by `yad-ui` (`epics/EP-<slug>/.sdlc/design-links.json`),
   not here.
-- Speak in the configured `communication_language`; write documents in `document_output_language`.
+- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.
 
 ## Inputs
 
@@ -94,7 +94,7 @@ Nothing auto-advances; this is setup.
   **available/unavailable** flag for the MCP (best-effort, the user's own session). No design tool
   connected ⇒ "markdown-only".
 - **`disconnect`** — remove the registry file (or set `tool: "none"`). The design tool's own
-  project/files are **never touched** — only the hub's record of them.
+  project/files are **never touched** — only the Product's record of them.
 
 ## Hard rules
 

package/skills/yad-connect-design/references/design-context.md

@@ -46,7 +46,7 @@ a screen, capture its node id + URL, and map components/tokens into `DESIGN.md`.
 
 Either direction ends by writing `epics/EP-<slug>/.sdlc/design-links.json` — the machine-readable
 screen→frame map — and a `## Design (<tool>)` section in `ui-design.md` linking each screen to its frame
-URL. The design itself lives in the tool; the hub keeps the *links* and the Markdown spec beside the
+URL. The design itself lives in the tool; the Product keeps the *links* and the Markdown spec beside the
 other epic artifacts.
 
 ## Degrade path (no MCP / no tool)