yadflow 2.15.0 → 2.16.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [2.15.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.14.0...v2.15.0) (2026-06-24)
+# [2.16.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.15.0...v2.16.0) (2026-06-25)
 
 
 ### Features
 
-* merge-driven review gate (Path B) — CI never pushes the review branch ([#78](https://github.com/abdelrahmannasr/yadflow/issues/78)) ([d4d983a](https://github.com/abdelrahmannasr/yadflow/commit/d4d983ab4efddb4e6ec259bb940b393e9237f9cf)), closes [#76](https://github.com/abdelrahmannasr/yadflow/issues/76)
+* make hub pr-title/pr-template gates branch-aware so tooling PRs pass ([#79](https://github.com/abdelrahmannasr/yadflow/issues/79)) ([68050e0](https://github.com/abdelrahmannasr/yadflow/commit/68050e000010b4d98f304a7e5e1f6a39bc0c229c))
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo). A BMAD module + 30 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/yad-checks/references/check-gates.md

@@ -121,8 +121,17 @@ from the event payload):
 - `--profile code` (default) → a Conventional-Commits subject `<type>: <description>`, no trailing
   period (`config.yaml build.pr_title_style: same_as_commit_subject` — one task = one PR, the title is
   the squash-merge subject).
-- `--profile hub` → a front-half artifact-review title `review: <artifact> (EP-<slug>)`, the shape
-  `yad gate open` creates.
+- `--profile hub` → splits by the PR/MR **head branch** (passed via `--head`, injected by CI):
+  - `review/EP-*` head (or no `--head` — stays strict) → a front-half artifact-review title
+    `review: <artifact> (EP-<slug>)`, the shape `yad gate open` creates.
+  - any other head → a tooling/code change to the hub itself, so it follows the `code` convention (a
+    Conventional-Commits subject). This is what lets a PR that changes the hub's own workflows/checks
+    pass — it has no EP artifact to review.
+  - **Anti-bypass guard.** The branch name alone is not trusted: a non-review head that actually
+    changes front-half artifacts (any path under `epics/**`) **FAILS** — those changes must go through
+    a `review/EP-*` PR and the artifact-review workflow. CI passes the PR's changed paths via
+    `--changed <file>` (computed from the diff against the base ref); without that list (a direct
+    by-hand caller) the guard is inert and the branch split alone applies.
 
 ## 7. pr-template (`templates/checks/pr-template.sh`)
 
@@ -131,8 +140,14 @@ catches a free-form description that bypassed it:
 
 - `--profile code` (default) → requires `## Summary`, `## Impact & Risk`, `## Checklist`, and a filled
   `Risk level:` (`low|medium|high`).
-- `--profile hub` → requires `## Artifact under review`, `## Impact & Risk (front-half)`, `## Checklist`,
-  and a `Risk tags:` line.
+- `--profile hub` → splits by the PR/MR **head branch** (passed via `--head`, injected by CI):
+  - `review/EP-*` head (or no `--head`) → requires the artifact-review template: `## Artifact under
+    review`, `## Impact & Risk (front-half)`, `## Checklist`, and a `Risk tags:` line.
+  - any other head → a hub tooling PR, so it requires the `code` task template (`## Summary`,
+    `## Impact & Risk`, `## Checklist`, filled `Risk level:`).
+  - **Anti-bypass guard** (same as pr-title): a non-review head that changes front-half artifacts
+    (`epics/**`, detected from the CI-supplied `--changed <file>` list) **FAILS** — artifact changes
+    must go through a `review/EP-*` PR.
 
 ## CI wiring (both platforms)
 
@@ -202,9 +217,12 @@ its one include line) whenever `.sdlc/hub.json` has a platform with the bridge e
 front-half review PRs are held to the same rule as code-repo PRs: signed, known authors only.
 
 The hub **also** runs the three pattern gates (`commit-message`, `pr-title`, `pr-template`) with
-`--profile hub`, so the front-half review PRs follow the hub conventions — Conventional-Commits commit
-subjects, a `review: <artifact> (EP-<slug>)` title, and a body that uses the hub artifact-review
-template. `yad check --fix` installs the same `checks/*.sh` scripts plus a standalone hub workflow
+`--profile hub`. The pattern gates split by the PR/MR **head branch** (passed via `--head`): a
+`review/EP-*` head is a front-half review PR — Conventional-Commits commit subjects, a
+`review: <artifact> (EP-<slug>)` title, and the hub artifact-review template body; **any other head is
+a tooling/code change to the hub itself** and follows the `code` convention (a Conventional-Commits
+title + the code task template), so a PR that changes the hub's own workflows/checks can pass.
+`yad check --fix` installs the same `checks/*.sh` scripts plus a standalone hub workflow
 (`templates/github/yad-hub-checks.yml` → `.github/workflows/yad-hub-checks.yml`, or the GitLab fragment
 `templates/gitlab/yad-hub-checks.gitlab-ci.yml` → `.gitlab/ci/yad-hub-checks.yml` + its one include
 line). Code repos run the same three with `--profile code` inside the main `yad-checks` workflow.

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

@@ -1,8 +1,11 @@
 # yad-managed: yad-checks
-# Pattern gates for the PRODUCT HUB: every PR (including the front-half review/EP-* PRs) must follow
-# the hub conventions — Conventional-Commits commit subjects, a `review: <artifact> (EP-<slug>)` PR
-# title, and a PR body that uses the hub artifact-review template. They run with `--profile hub`.
-# Standalone workflow so it never collides with the code-repo yad-checks workflow.
+# 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
+#     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
 on:
   pull_request:
@@ -17,23 +20,34 @@ jobs:
       - run: bash checks/commit-message.sh --profile hub "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
+  # change (epics/**) riding a non-review head past the front-half review with a plain code title.
   pr-title:
     runs-on: ubuntu-latest
     env:
       PR_TITLE: ${{ github.event.pull_request.title }}
+      PR_HEAD: ${{ github.event.pull_request.head.ref }}
+      BASE_REF: ${{ github.base_ref }}
     steps:
       - uses: actions/checkout@v4
-      - run: bash checks/pr-title.sh --profile hub "$PR_TITLE"
+        with: { fetch-depth: 0 }
+      - run: |
+          changed="$(mktemp)"; git diff --name-only "origin/${BASE_REF}...HEAD" > "$changed"
+          bash checks/pr-title.sh --profile hub --head "$PR_HEAD" --changed "$changed" "$PR_TITLE"
 
   pr-template:
     runs-on: ubuntu-latest
     env:
       PR_BODY: ${{ github.event.pull_request.body }}
+      PR_HEAD: ${{ github.event.pull_request.head.ref }}
+      BASE_REF: ${{ github.base_ref }}
     steps:
       - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
       - run: |
+          changed="$(mktemp)"; git diff --name-only "origin/${BASE_REF}...HEAD" > "$changed"
           body="$(mktemp)"; printf '%s' "$PR_BODY" > "$body"
-          bash checks/pr-template.sh --profile hub "$body"
+          bash checks/pr-template.sh --profile hub --head "$PR_HEAD" --changed "$changed" "$body"
 
   # The gate ledger is CI-owned: reject non-bot commits to .sdlc/*.json or reviews/*.md.
   ledger-guard:

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

@@ -3,9 +3,11 @@
 # .gitlab-ci.yml via:
 #   include:
 #     - local: '.gitlab/ci/yad-hub-checks.yml'
-# Every MR (including the front-half review/EP-* MRs) must follow the hub conventions — a
-# Conventional-Commits commit subject, a `review: <artifact> (EP-<slug>)` MR title, and an MR body
-# that uses the hub artifact-review template. They run with `--profile hub`.
+# 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
+# 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
 # `needs: []` and no `stage:` so a foreign `stages:` list can neither break nor reorder them.
 default:
@@ -25,18 +27,22 @@ yad-hub-commit-message:
   script:
     - 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.
 yad-hub-pr-title:
   extends: .yad_hub_mr_only
   needs: []
   script:
-    - bash checks/pr-title.sh --profile hub "$CI_MERGE_REQUEST_TITLE"
+    - changed="$(mktemp)"; git diff --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"
 
 yad-hub-pr-template:
   extends: .yad_hub_mr_only
   needs: []
   script:
+    - changed="$(mktemp)"; git diff --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 "$body"
+    - bash checks/pr-template.sh --profile hub --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --changed "$changed" "$body"
 
 # The gate ledger is CI-owned: reject non-bot commits to .sdlc/*.json or reviews/*.md.
 yad-hub-ledger-guard:

package/skills/yad-pr-template/templates/checks/pr-template.sh

@@ -7,21 +7,38 @@
 #     requires `## Summary`, `## Impact & Risk`, `## Checklist`, and a filled `Risk level:` (low|medium|high).
 #   --profile hub — the front-half artifact-review template (templates/hub/<platform>/):
 #     requires `## Artifact under review`, `## Impact & Risk (front-half)`, `## Checklist`, and a `Risk tags:` line.
+#     BUT only for review/EP-* head branches. Every other hub PR is a tooling/code change to the hub
+#     itself and uses the code task template instead; pass the head ref via --head so the gate knows
+#     which template to require. With no --head, the hub profile stays strict (artifact-review template).
+#     Branch name is not enough on its own: a non-review head that actually changes front-half
+#     artifacts (epics/**) would otherwise slip past the review workflow with only the code template.
+#     Pass the PR's changed paths via --changed <file> (one path per line); when they touch epics/**
+#     on a non-review head the gate FAILS — artifact changes must go through a review/EP-* PR.
 # The body is passed as a FILE path (single positional arg); CI writes the event body to a temp file
 # (GitHub: github.event.pull_request.body; GitLab: $CI_MERGE_REQUEST_DESCRIPTION).
 set -euo pipefail
 
 PROFILE=code
+HEADREF=""
+CHANGED=""
 ARGS=()
 while [ $# -gt 0 ]; do
   case "$1" in
     --profile) PROFILE="${2:-code}"; shift 2 ;;
     --profile=*) PROFILE="${1#*=}"; shift ;;
+    --head) HEADREF="${2:-}"; shift 2 ;;
+    --head=*) HEADREF="${1#*=}"; shift ;;
+    --changed) CHANGED="${2:-}"; shift 2 ;;
+    --changed=*) CHANGED="${1#*=}"; shift ;;
     *) ARGS+=("$1"); shift ;;
   esac
 done
 case "$PROFILE" in code|hub) ;; *) echo "FAIL [pr-template]: unknown --profile '$PROFILE' (code|hub)."; exit 1 ;; esac
 
+# True when the PR changes a front-half artifact (anything under epics/**). Reads the --changed list
+# of paths CI computed from the PR diff; with no list (direct caller / test) it reports false.
+artifact_changed() { [ -n "$CHANGED" ] && [ -f "$CHANGED" ] && grep -qE '^epics/' "$CHANGED"; }
+
 BODY="${ARGS[0]:-}"
 if [ -z "$BODY" ] || [ ! -f "$BODY" ]; then
   echo "FAIL [pr-template]: body file not found — pass the PR/MR description as a file path."
@@ -36,19 +53,14 @@ require_heading() {
   fi
 }
 
-if [ "$PROFILE" = hub ]; then
-  require_heading '## Artifact under review' '## Artifact under review'
-  require_heading '## Impact & Risk \(front-half\)' '## Impact & Risk (front-half)'
-  require_heading '## Checklist' '## Checklist'
-  if ! grep -qiE '(\*\*)?Risk tags:' "$BODY"; then
-    echo "FAIL [pr-template]: missing 'Risk tags:' line (front-half Impact & Risk)."
-    rc=1
-  fi
-else
+# The code task template: `## Summary`, `## Impact & Risk`, `## Checklist`, and a filled `Risk level:`.
+# Used by the code profile and by hub tooling PRs (any head branch that is not review/EP-*).
+check_code_body() {
   require_heading '## Summary' '## Summary'
   require_heading '## Impact & Risk' '## Impact & Risk'
   require_heading '## Checklist' '## Checklist'
   # Risk level must be present AND filled with a real value (not the <placeholder>).
+  local rl
   rl="$(grep -iE '(\*\*)?Risk level:' "$BODY" | head -1 \
         | sed -E 's/<!--.*$//; s/^[^:]*://; s/[*`]//g; s/^[[:space:]]*//; s/[[:space:]]*$//' || true)"
   rl="$(printf '%s' "$rl" | tr 'A-Z' 'a-z' | grep -oE 'low|medium|high' | head -1 || true)"
@@ -56,7 +68,38 @@ else
     echo "FAIL [pr-template]: 'Risk level:' missing or not set to low|medium|high."
     rc=1
   fi
+}
+
+# The front-half artifact-review template.
+check_hub_body() {
+  require_heading '## Artifact under review' '## Artifact under review'
+  require_heading '## Impact & Risk \(front-half\)' '## Impact & Risk (front-half)'
+  require_heading '## Checklist' '## Checklist'
+  if ! grep -qiE '(\*\*)?Risk tags:' "$BODY"; then
+    echo "FAIL [pr-template]: missing 'Risk tags:' line (front-half Impact & Risk)."
+    rc=1
+  fi
+}
+
+KIND="$PROFILE"
+if [ "$PROFILE" = hub ]; then
+  case "$HEADREF" in
+    review/EP-*|"") check_hub_body ;;            # artifact-review PR (or unknown head — stay strict)
+    *)
+      # tooling/code change to the hub itself — UNLESS it changes front-half artifacts (epics/**),
+      # which must go through a review/EP-* PR. Without this guard a non-review head could carry an
+      # artifact change past the front-half review with only the code template.
+      if artifact_changed; then
+        echo "FAIL [pr-template]: head '${HEADREF}' changes front-half artifacts (epics/**) but is not a review/EP-* branch — artifact changes must go through a review PR."
+        rc=1
+      else
+        check_code_body; KIND="hub-tooling"
+      fi
+      ;;
+  esac
+else
+  check_code_body
 fi
 
-[ "$rc" = 0 ] && echo "PASS [pr-template]: body uses the ${PROFILE} template (required sections present)."
+[ "$rc" = 0 ] && echo "PASS [pr-template]: body uses the ${KIND} template (required sections present)."
 exit "$rc"

package/skills/yad-pr-template/templates/checks/pr-title.sh

@@ -5,22 +5,39 @@
 #     period (config.yaml build.pr_title_style: same_as_commit_subject; one task = one PR, the title is
 #     the squash-merge subject). Keep <type> in sync with cli/manifest.mjs COMMIT_TYPES.
 #   --profile hub — a front-half artifact-review title "review: <artifact> (EP-<slug>)", the shape
-#     `yad gate open` creates (cli/gate.mjs).
+#     `yad gate open` creates (cli/gate.mjs) — BUT only for review/EP-* head branches. Every other
+#     hub PR is a tooling/code change to the hub itself and follows the code convention; pass the
+#     head ref via --head so the gate can tell the two apart (a tooling PR has no EP artifact to
+#     review). With no --head, the hub profile stays strict (requires the review shape).
+#     Branch name is not enough on its own: a non-review head that actually changes front-half
+#     artifacts (epics/**) would otherwise slip past the review workflow with a plain code title.
+#     Pass the PR's changed paths via --changed <file> (one path per line); when they touch epics/**
+#     on a non-review head the gate FAILS — artifact changes must go through a review/EP-* PR.
 # The title is passed as the (single) positional arg; CI injects it from the event payload
 # (GitHub: github.event.pull_request.title; GitLab: $CI_MERGE_REQUEST_TITLE).
 set -euo pipefail
 
 PROFILE=code
+HEADREF=""
+CHANGED=""
 ARGS=()
 while [ $# -gt 0 ]; do
   case "$1" in
     --profile) PROFILE="${2:-code}"; shift 2 ;;
     --profile=*) PROFILE="${1#*=}"; shift ;;
+    --head) HEADREF="${2:-}"; shift 2 ;;
+    --head=*) HEADREF="${1#*=}"; shift ;;
+    --changed) CHANGED="${2:-}"; shift 2 ;;
+    --changed=*) CHANGED="${1#*=}"; shift ;;
     *) ARGS+=("$1"); shift ;;
   esac
 done
 case "$PROFILE" in code|hub) ;; *) echo "FAIL [pr-title]: unknown --profile '$PROFILE' (code|hub)."; exit 1 ;; esac
 
+# True when the PR changes a front-half artifact (anything under epics/**). Reads the --changed list
+# of paths CI computed from the PR diff; with no list (direct caller / test) it reports false.
+artifact_changed() { [ -n "$CHANGED" ] && [ -f "$CHANGED" ] && grep -qE '^epics/' "$CHANGED"; }
+
 TITLE="${ARGS[0]:-}"
 if [ -z "$TITLE" ]; then
   echo "FAIL [pr-title]: empty title — pass the PR/MR title as the argument."
@@ -29,23 +46,43 @@ fi
 
 TYPES='feat|fix|docs|refactor|test|perf|build|ci|chore|revert'
 
-if [ "$PROFILE" = hub ]; then
-  # review: <artifact> (EP-<slug>)
-  if printf '%s' "$TITLE" | grep -qE '^review: .+ \(EP-[a-z0-9-]+\)$'; then
-    echo "PASS [pr-title]: '${TITLE}' (profile: hub)"
-    exit 0
+# Conventional-Commits subject (optional scope + breaking `!`), no trailing period. Used by the code
+# profile and by hub tooling PRs (any head branch that is not review/EP-*).
+check_code_title() {
+  if ! printf '%s' "$TITLE" | grep -qE "^(${TYPES})(\([a-z0-9._-]+\))?!?: .+"; then
+    echo "FAIL [pr-title]: '${TITLE}' is not '<type>(<scope>)?!?: <description>' (type one of: ${TYPES//|/, })."
+    exit 1
   fi
-  echo "FAIL [pr-title]: '${TITLE}' is not a hub review title 'review: <artifact> (EP-<slug>)'."
-  exit 1
-fi
+  if printf '%s' "$TITLE" | grep -qE '\.$'; then
+    echo "FAIL [pr-title]: '${TITLE}' must not end with a period."
+    exit 1
+  fi
+  echo "PASS [pr-title]: '${TITLE}' (profile: ${PROFILE}, tooling/code)"
+  exit 0
+}
 
-# code profile — Conventional-Commits subject (optional scope + breaking `!`), no trailing period.
-if ! printf '%s' "$TITLE" | grep -qE "^(${TYPES})(\([a-z0-9._-]+\))?!?: .+"; then
-  echo "FAIL [pr-title]: '${TITLE}' is not '<type>(<scope>)?!?: <description>' (type one of: ${TYPES//|/, })."
-  exit 1
-fi
-if printf '%s' "$TITLE" | grep -qE '\.$'; then
-  echo "FAIL [pr-title]: '${TITLE}' must not end with a period."
-  exit 1
+if [ "$PROFILE" = hub ]; then
+  # review/EP-* head branch (or unknown head ref) => front-half artifact-review PR: 'review: <artifact> (EP-<slug>)'.
+  case "$HEADREF" in
+    review/EP-*|"")
+      if printf '%s' "$TITLE" | grep -qE '^review: .+ \(EP-[a-z0-9-]+\)$'; then
+        echo "PASS [pr-title]: '${TITLE}' (profile: hub, artifact-review)"
+        exit 0
+      fi
+      echo "FAIL [pr-title]: '${TITLE}' is not a hub review title 'review: <artifact> (EP-<slug>)'."
+      exit 1
+      ;;
+    *)
+      # Any other hub PR is a tooling/code change to the hub itself — UNLESS it changes front-half
+      # artifacts (epics/**), which must go through a review/EP-* PR. Without this guard a non-review
+      # head could carry an artifact change past the front-half review with only a code title.
+      if artifact_changed; then
+        echo "FAIL [pr-title]: head '${HEADREF}' changes front-half artifacts (epics/**) but is not a review/EP-* branch — artifact changes must go through a review PR."
+        exit 1
+      fi
+      # tooling only — fall through to the code convention.
+      ;;
+  esac
 fi
-echo "PASS [pr-title]: '${TITLE}' (profile: code)"
+
+check_code_title