yadflow 2.5.0 → 2.6.0

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

@@ -12,6 +12,9 @@ repo uses. Each reads conventions established by earlier steps — it invents no
 | contract-check | changed files under `specs/<story>/contracts/`; the `Contract-Change: yes` trailer; `link.md`'s pinned `contract-lock`; the product repo's `contract-lock.json` | `yad-architecture` (lock), `yad-spec` (slice + link), `yad-implement` (trailer) |
 | build/test/lint | the repo's `npm run lint` / `npm run build` / `npm test` | the repo |
 | verified-commits | each commit's platform signature-verification status; the author email vs `.sdlc/verified-authors` | hub roster `email` fields (`yad check --fix` generates the allowlist) |
+| commit-message | each non-merge commit's subject + trailer block | `yad-commit` / `CONTRIBUTING.md` (`config.yaml build.commit_subject_style`) |
+| pr-title | the PR/MR title (from the CI event payload) | `yad-pr-template` (`config.yaml build.pr_title_style`) |
+| pr-template | the PR/MR body (from the CI event payload) | `yad-pr-template` (the committed PR/MR template) |
 
 ## 1. spec-link (`templates/checks/spec-link.sh`)
 
@@ -84,16 +87,54 @@ Note the deliberate split with the gate-sync bot: this gate runs on **PRs/MRs on
 not subject to it. Do **not** replace it with a platform-level "reject unsigned pushes" rule on the
 default branch — that would break the event-driven gate sync (and GitLab push rules are Premium-only).
 
+## 5. commit-message (`templates/checks/commit-message.sh`)
+
+The commit *pattern* gate (the presence-only `Task:` check is spec-link's; this checks SHAPE). For each
+non-merge commit in `<base>..HEAD`:
+
+- **Subject** must be `<type>: <description>` with `<type>` a known Conventional-Commits type
+  (`feat|fix|docs|refactor|test|perf|build|ci|chore|revert` — keep in sync with `cli/manifest.mjs`
+  `COMMIT_TYPES`) and **no trailing period** — mirroring `cli/commit.mjs` `buildCommitMessage`.
+- **Trailers**, when present, appear in the fixed order `Task → Contract-Change → Co-Authored-By`.
+- Merge/squash commits (2+ parents) are skipped — their platform-generated subjects are not authored.
+- **Profiles** (`--profile code|hub`): the subject rule is identical on both; the gate never requires
+  the `Task:` trailer (spec-link owns that on code repos; hub commits are not task-scoped).
+- **Fails closed** when `<base>` can't be resolved.
+
+## 6. pr-title (`templates/checks/pr-title.sh`)
+
+The PR/MR title must follow the convention for the repo kind (title passed as the arg, injected by CI
+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.
+
+## 7. pr-template (`templates/checks/pr-template.sh`)
+
+The PR/MR body must actually USE the committed template (body passed as a file, injected by CI) — this
+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.
+
 ## CI wiring (both platforms)
 
 The gates run identically under either CI; the config just invokes the scripts with the PR/MR base.
 
 - **GitHub Actions** — `templates/github/yad-checks.yml` → `.github/workflows/yad-checks.yml`. The
   jobs run on `pull_request` with `fetch-depth: 0`, passing `origin/${{ github.base_ref }}` as base
-  (verified-commits also gets a read-only `GH_TOKEN` for the Verified-badge lookup).
+  (verified-commits also gets a read-only `GH_TOKEN` for the Verified-badge lookup). The pattern jobs
+  read the title/body from the event payload: `pr-title` takes `${{ github.event.pull_request.title }}`
+  and `pr-template` writes `${{ github.event.pull_request.body }}` to a temp file. All `--profile code`.
 - **GitLab CI** — `templates/gitlab/yad-checks.gitlab-ci.yml` → `.gitlab/ci/yad-checks.yml`, pulled in
   by the root `.gitlab-ci.yml`'s `include:`. The jobs run on `merge_request_event` with `GIT_DEPTH: 0`,
-  passing `origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME`.
+  passing `origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME`; the pattern jobs read `$CI_MERGE_REQUEST_TITLE`
+  and `$CI_MERGE_REQUEST_DESCRIPTION`. All `--profile code`.
 
 ## Sync with existing CI (merge, never clobber)
 
@@ -148,6 +189,14 @@ plus a standalone workflow (`templates/github/yad-verified-commits.yml` →
 its one include line) whenever `.sdlc/hub.json` has a platform with the bridge enabled. So the
 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
+(`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.
+
 ## Running by hand (Phase 3 is manual)
 
 From inside the code repo, against the PR/MR base (e.g. `master`):
@@ -157,6 +206,13 @@ bash checks/spec-link.sh master
 bash checks/contract-check.sh master
 bash checks/build-test-lint.sh
 bash checks/verified-commits.sh master   # uses your own gh/glab auth for the signature lookup
+bash checks/commit-message.sh --profile code master
+# pr-title / pr-template validate the actual PR/MR metadata (in CI they come from the event payload).
+# By hand, pass the title, and a FILE holding the PR/MR description (the rendered/filled body, not the
+# template source):
+bash checks/pr-title.sh --profile code "feat: add the inquiry endpoint"
+# save the PR/MR description to a file first (e.g. `gh pr view <n> --json body -q .body > /tmp/pr-body.md`)
+bash checks/pr-template.sh --profile code /tmp/pr-body.md
 ```
 
 ## Proven behavior (demo: `demo-repos/backend`, story EP-istifta-inquiries-S01)

package/skills/yad-checks/templates/checks/commit-message.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# commit-message gate.
+# Every non-merge commit in the range under review must follow the project commit convention
+# (CONTRIBUTING.md / config.yaml build — mirrors cli/commit.mjs buildCommitMessage):
+#   - subject is "<type>: <description>" where <type> is a known Conventional-Commits type,
+#   - the subject does NOT end with a period,
+#   - any trailers appear in the fixed order Task -> Contract-Change -> Co-Authored-By.
+# Keep the type list in sync with cli/manifest.mjs COMMIT_TYPES and config.yaml build.commit_subject_style.
+#
+# Profiles (--profile code|hub, default code): the subject rule is identical on the product hub and on
+# code repos (both follow CONTRIBUTING). The Task trailer is NOT required here (the spec-link gate owns
+# that on code repos; hub commits are not task-scoped) — this gate only checks SHAPE and ORDER.
+#
+# Merge/squash commits (2+ parents) are skipped: their platform-generated subjects are not authored.
+set -euo pipefail
+
+PROFILE=code
+ARGS=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --profile) PROFILE="${2:-code}"; shift 2 ;;
+    --profile=*) PROFILE="${1#*=}"; shift ;;
+    *) ARGS+=("$1"); shift ;;
+  esac
+done
+case "$PROFILE" in code|hub) ;; *) echo "FAIL [commit-message]: unknown --profile '$PROFILE' (code|hub)."; exit 1 ;; esac
+
+BASE="${ARGS[0]:-${SDLC_BASE:-origin/main}}"
+
+# Fail closed if the base ref can't be resolved (shallow clone / wrong base branch / unfetched ref).
+if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
+  echo "FAIL [commit-message]: base ref '${BASE}' not found — fetch full history / check the base branch."
+  exit 1
+fi
+RANGE="${BASE}..HEAD"
+
+# Conventional-Commits types — keep in sync with cli/manifest.mjs COMMIT_TYPES.
+TYPES='feat|fix|docs|refactor|test|perf|build|ci|chore|revert'
+
+commits="$(git rev-list --no-merges "$RANGE")"
+if [ -z "$commits" ]; then
+  echo "PASS [commit-message]: no non-merge commits in ${RANGE} (profile: ${PROFILE})"
+  exit 0
+fi
+
+rc=0
+while IFS= read -r sha; do
+  [ -z "$sha" ] && continue
+  short="$(git log -1 --format=%h "$sha")"
+  subject="$(git log -1 --format=%s "$sha")"
+
+  # 1) subject shape: "<type>(<optional scope>)<optional !>: <non-empty description>"
+  #    (scope + breaking-change `!` are allowed per CONTRIBUTING.md).
+  if ! printf '%s' "$subject" | grep -qE "^(${TYPES})(\([a-z0-9._-]+\))?!?: .+"; then
+    echo "FAIL [commit-message]: ${short} subject '${subject}' is not '<type>(<scope>)?!?: <description>' (type one of: ${TYPES//|/, })."
+    rc=1
+  # 2) no trailing period on the subject
+  elif printf '%s' "$subject" | grep -qE '\.$'; then
+    echo "FAIL [commit-message]: ${short} subject '${subject}' must not end with a period."
+    rc=1
+  else
+    echo "PASS [commit-message]: ${short} '${subject}'"
+  fi
+
+  # 3) trailer order Task -> Contract-Change -> Co-Authored-By (only among those present).
+  #    Parse ONLY the trailing trailer block (git interpret-trailers) so a body prose line that
+  #    happens to start with a trailer key is never mistaken for a trailer.
+  trailers="$(git log -1 --format=%B "$sha" | git interpret-trailers --parse 2>/dev/null || true)"
+  lt="$(printf '%s\n' "$trailers" | grep -niE '^Task:' | head -1 | cut -d: -f1 || true)"
+  lc="$(printf '%s\n' "$trailers" | grep -niE '^Contract-Change:' | head -1 | cut -d: -f1 || true)"
+  lo="$(printf '%s\n' "$trailers" | grep -niE '^Co-Authored-By:' | head -1 | cut -d: -f1 || true)"
+  if { [ -n "$lt" ] && [ -n "$lc" ] && [ "$lt" -gt "$lc" ]; } \
+     || { [ -n "$lt" ] && [ -n "$lo" ] && [ "$lt" -gt "$lo" ]; } \
+     || { [ -n "$lc" ] && [ -n "$lo" ] && [ "$lc" -gt "$lo" ]; }; then
+    echo "FAIL [commit-message]: ${short} trailers out of order — expected Task -> Contract-Change -> Co-Authored-By."
+    rc=1
+  fi
+done <<EOF
+$commits
+EOF
+
+exit "$rc"

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

@@ -32,6 +32,33 @@ jobs:
         with: { node-version: "20" }
       - run: bash checks/build-test-lint.sh
 
+  # Pattern gates: commit subject + PR title + PR body all follow the convention (profile: code).
+  commit-message:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - run: bash checks/commit-message.sh --profile code "origin/${{ github.base_ref }}"
+
+  # Pass the title via env (never interpolate untrusted ${{ }} into a run line — injection-safe).
+  pr-title:
+    runs-on: ubuntu-latest
+    env:
+      PR_TITLE: ${{ github.event.pull_request.title }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: bash checks/pr-title.sh --profile code "$PR_TITLE"
+
+  pr-template:
+    runs-on: ubuntu-latest
+    env:
+      PR_BODY: ${{ github.event.pull_request.body }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          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.
   verified-commits:
     runs-on: ubuntu-latest

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

@@ -0,0 +1,36 @@
+# 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.
+name: yad-hub-checks
+on:
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  commit-message:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - 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).
+  pr-title:
+    runs-on: ubuntu-latest
+    env:
+      PR_TITLE: ${{ github.event.pull_request.title }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: bash checks/pr-title.sh --profile hub "$PR_TITLE"
+
+  pr-template:
+    runs-on: ubuntu-latest
+    env:
+      PR_BODY: ${{ github.event.pull_request.body }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          body="$(mktemp)"; printf '%s' "$PR_BODY" > "$body"
+          bash checks/pr-template.sh --profile hub "$body"

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

@@ -45,6 +45,26 @@ yad-build-test-lint:
   script:
     - bash checks/build-test-lint.sh
 
+# Pattern gates: commit subject + MR title + MR body all follow the convention (profile: code).
+yad-commit-message:
+  extends: .sdlc_mr_only
+  needs: []
+  script:
+    - bash checks/commit-message.sh --profile code "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+
+yad-pr-title:
+  extends: .sdlc_mr_only
+  needs: []
+  script:
+    - bash checks/pr-title.sh --profile code "$CI_MERGE_REQUEST_TITLE"
+
+yad-pr-template:
+  extends: .sdlc_mr_only
+  needs: []
+  script:
+    - 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.
 # 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.

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

@@ -0,0 +1,39 @@
+# yad-managed-include: yad-checks
+# Pattern gates for the PRODUCT HUB, as an INCLUDABLE fragment. Pulled into the hub's root
+# .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`.
+# 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:
+  image: node:20
+  tags: [$YAD_RUNNER_TAGS]
+
+.yad_hub_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
+  needs: []
+  script:
+    - bash checks/commit-message.sh --profile hub "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+
+yad-hub-pr-title:
+  extends: .yad_hub_mr_only
+  needs: []
+  script:
+    - bash checks/pr-title.sh --profile hub "$CI_MERGE_REQUEST_TITLE"
+
+yad-hub-pr-template:
+  extends: .yad_hub_mr_only
+  needs: []
+  script:
+    - body="$(mktemp)"; printf '%s' "$CI_MERGE_REQUEST_DESCRIPTION" > "$body"
+    - bash checks/pr-template.sh --profile hub "$body"

package/skills/yad-commit/SKILL.md

@@ -0,0 +1,66 @@
+---
+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 block (Task → Contract-Change → Co-Authored-By), and an atomic-file guard (≤3 files). The human git author OWNS the commit; an assisting AI is recorded only as a Co-Authored-By footer, chosen per-commit with --ai (claude|copilot|cursor|coderabbit|none — default none, human-only). 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)
+
+**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
+`Task → Contract-Change → Co-Authored-By`, and the atomic-file guard. This is the standalone commit
+step — the same engine `yad-implement` 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.
+- **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
+  `feat|fix|docs|refactor|test|perf|build|ci|chore|revert`; proper nouns/acronyms keep their case.
+- **Task trailer** — required on a code repo (anchors the `spec-link` + `commit-message` gates). Given
+  with `--task`, else derived from the branch (`feat/<story>-<task>-…`). Hub commits are not
+  task-scoped, so the trailer is optional there.
+- **Contract-Change trailer** — `--contract-change` only when the diff touches the locked contract
+  surface; it routes the change back to the architecture gate.
+- **AI co-author footer** — `--ai <id>` records the assisting tool as a `Co-Authored-By` trailer. The
+  human is always the author; `--ai none` (the default) is an explicit human-only commit.
+
+## Inputs
+
+- `type`    — Conventional-Commits type (required).
+- `message` — the subject text (required), `-m "<subject>"`.
+- `ai`      — co-author footer: `claude|copilot|cursor|coderabbit|none` (default `none`).
+- `task`    — Task trailer (optional; derived from the branch when omitted).
+- `contractChange` — flag; mark the contract surface touched.
+
+## On Activation
+
+### Step 1 — Confirm the atomic stage
+Confirm the change is staged and stays within the file boundary (≤3 files where possible). If more is
+staged, split it into separate commits rather than passing `--force`.
+
+### Step 2 — Commit by convention
+Run the CLI from the repo root:
+```
+yad commit --type <type> -m "<subject>" [--ai <id>] [--task <id>] [--contract-change] [--dry-run]
+```
+Use `--dry-run` first to preview the exact message (subject + trailer block) without committing. The
+CLI validates the type, rejects a trailing period, and emits the trailers in the fixed order.
+
+### Step 3 — Stop (no auto-advance)
+Report what was committed (files + Task). If `--contract-change` was set, note that it routes back to
+the architecture gate. To also open the PR/MR in the same step, use `yad-ship`.
+
+## Hard rules
+
+- **One staged atomic change = one commit.** Never bundle; never exceed the file boundary silently.
+- **The human author owns the commit.** The AI is only a `Co-Authored-By` footer, chosen per-commit.
+- **Trailer order is fixed:** `Task → Contract-Change → Co-Authored-By`.
+- **Never widen the contract here.** A contract touch is flagged (`--contract-change`), not hidden.
+
+## 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 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-engineer-review/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: yad-engineer-review
+description: 'Build-half Step E of the gated SDLC — AI review, engineer review, then merge. Wire an advisory AI first-pass (CodeRabbit) on the PR/MR; record the human engineer review with the same human_approve discipline as the front gates (owner + 1 reviewer, escalating to domain owners on high risk / contract / auth / payments — the Step D routing); and on merge, record the ship in the epic build-log and update the story state so the epic → story → task → PR chain is traceable. Never auto-advances — the human owns the merge. Use when the user says "record the engineer review", "merge this task", or "wire the AI review". (To commit + open the PR/MR, use yad-ship.)'
+---
+
+# SDLC — Engineer Review & Merge (build-half Step E)
+
+**Goal:** Take a task PR/MR that has passed the **check gates** (Step C) through two sets of eyes and
+out to production: an **AI first-pass** (advisory) and a **human engineer review** (the authority),
+then **ship** — merge, record the ship, and update the story state. This is the last build-half step
+(build plan §E). It is a **human gate**, the same `human_approve` discipline as the front states:
+**nothing auto-advances**; the engineer owns the merge.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory — the **product** repo (the source of
+  truth: it holds the story and the build ledger).
+- Code repos are separate git repos under `{project-root}/demo-repos/<repo>/`.
+- The build ledger is `{project-root}/epics/<epic>/.sdlc/build-log.json` (append-only).
+- The engineer-review rule reuses `yad-review-gate`: base = at least one `owner` AND one distinct
+  `reviewer`; **escalated** (the PR's Impact & Risk is `high`, or it touches contract/auth/payments) =
+  base PLUS one `domain-owner` per touched domain — the same routing `yad-pr-template`'s
+  `risk-route.sh` prints.
+- AI review wiring: `templates/.coderabbit.yaml` → `<repo>/.coderabbit.yaml`.
+
+## Inputs
+
+- `epic` / `story` / `task` / `repo` — the PR under review (the task branch `feat/<story>-<task>-…`).
+- `action` — `ai-review` | `approve` | `ship` (default `ai-review`).
+- For `approve`: the reviewer `name` and `role` (`owner` | `reviewer` | `domain-owner`), and for a
+  domain owner the `domain`.
+
+## On Activation
+
+### Step 1 — `ai-review` (advisory first pass)
+Ensure the AI reviewer is wired: copy `templates/.coderabbit.yaml` to `<repo>/.coderabbit.yaml` (commit
+on the default branch if missing). CodeRabbit reviews each PR automatically and posts comments — it is
+a **second set of eyes, never the authority**: it cannot approve or merge. Where CodeRabbit can't run
+(no remote), run an equivalent AI first-pass by hand and capture its notes. Record that the AI review
+ran; surface its findings to the engineer. Do **not** treat AI approval as a gate.
+
+### Step 2 — `approve` (the engineer review — the human gate)
+A human engineer reads the diff **against the spec** (`specs/<story>/`) and the acceptance criteria,
+and records an approval. Determine the rule from the PR's Impact & Risk block (run
+`../yad-pr-template/templates/checks/risk-route.sh` on the PR body): base, or escalated to a
+domain-owner per touched domain. Record each approval; re-evaluate whether the rule is satisfied.
+Recording an approval does **not** ship — shipping is a separate, explicit step. Front-half discipline:
+the gate talks only through files; refuse to treat AI review as a human approval.
+
+### Step 3 — `ship` (merge + record + update state)
+Ship **iff ALL hold**: the check gates pass (Step C), the AI review has run (advisory), and the
+engineer-review rule is satisfied (Step 2). Then:
+- **Merge** the task branch into the repo's default branch (the human performs/authorises the merge).
+- **Record the ship** — append to `epics/<epic>/.sdlc/build-log.json`:
+  ```json
+  { "story": "<story>", "task": "<task>", "repo": "<repo>", "branch": "feat/<story>-<task>-…",
+    "pr": "<url|#>", "mergeCommit": "<sha>", "gates": ["spec-link","contract-check","build-test-lint"],
+    "ai_review": "coderabbit (advisory)", "engineer_review": [{"approver":"<name>","role":"<role>","domain":"<opt>"}],
+    "risk": "<low|medium|high>", "shippedAt": "<YYYY-MM-DD>" }
+  ```
+- **Update the story state** — when **every** task in `specs/<story>/tasks.md` has a ship record, set
+  the story frontmatter `status: shipped`; otherwise `status: in-build`. The chain
+  **epic → story → task → PR → mergeCommit** is now traceable end to end.
+- **Finalize the trust verdict (Phase 4).** If this story has a `build-state/<story>.json` (it ran
+  through `yad-run`), the engineer **confirms or overrides** the provisional trust verdict that the
+  orchestrator derived for this run, and the final verdict is written to
+  `epics/<epic>/.sdlc/trust-log.json`. The human has the last word on the trust signal: a diff merged
+  as authored is `approved-unchanged`; one the engineer edited before merge is `approved-with-edits`;
+  a rejected one is `rejected`. This is the evidence that later earns a step its `machine_advance`
+  (it never weakens the merge gate — the engineer still owns the merge).
+
+### Step 4 — Stop
+Report what shipped and the story's state. Do not advance anything else; the front-half `state.json`
+stays as it was (`ready-for-build`). The build half is recorded in `build-log.json` + the story status.
+
+## Hard rules (build plan §E, Cross-cutting)
+
+- **AI review is advisory, never the authority.** Only a human engineer approval counts toward the gate.
+- **High risk routes to domain owners** — the same escalation as `yad-review-gate` / `risk-route.sh`.
+- **Ship only after gates + engineer review.** No gate skipped; the human owns the merge.
+- **Nothing auto-advances.** Step E records human decisions in files; it never machine-advances.
+
+## Reference
+- The build ledger + story-state rules: `references/ship-and-record.md`.
+- The escalation reused: `../yad-review-gate/SKILL.md`; the routing helper: `../yad-pr-template/`.
+- The gates that must pass first: `../yad-checks/references/check-gates.md`.

package/skills/{yad-ship → yad-engineer-review}/references/ship-and-record.md

@@ -1,6 +1,6 @@
 # Ship — the build ledger and the story state
 
-Step E (`yad-ship`) closes the build half: AI review (advisory) → engineer review (the human gate) →
+Step E (`yad-engineer-review`) closes the build half: AI review (advisory) → engineer review (the human gate) →
 ship. Shipping records the merge and updates the story state so the whole chain is traceable.
 
 ## Two sets of eyes
@@ -64,4 +64,4 @@ trailer → story → epic).
 2. The **AI review** has run (advisory; findings surfaced to the engineer).
 3. The **engineer review** rule is satisfied (base or escalated per the Impact & Risk block).
 
-Only then does the human merge and `yad-ship` record it. Nothing auto-advances.
+Only then does the human merge and `yad-engineer-review` record it. Nothing auto-advances.

package/skills/{yad-ship → yad-engineer-review}/templates/.coderabbit.yaml

@@ -1,6 +1,6 @@
 # CodeRabbit — AI first-pass review (Phase 3 build plan §E).
 # Advisory only: a second set of eyes that COMMENTS on every PR. It never approves or merges — the
-# human engineer review (yad-review-gate discipline) owns that decision. See skills/yad-ship.
+# human engineer review (yad-review-gate discipline) owns that decision. See skills/yad-engineer-review.
 language: en
 reviews:
   request_changes_workflow: false   # never block the merge — the engineer review is the gate

package/skills/yad-epic/references/state-schema.md

@@ -216,7 +216,7 @@ base** that decides when a step is safe to automate (build plan Step A). One ent
 |------|---------|-------------------------------|
 | `spec` | `human_edited_spec` | the human who accepts `specs/<story>/` (`yad-spec` Step 8) |
 | `tasks` | `task_rescoped` | first consume by `yad-implement` (Step 8) |
-| `implement` | `human_edited_diff`, `scope_overrun`, `contract_touch` | engineer review at `yad-ship` |
+| `implement` | `human_edited_diff`, `scope_overrun`, `contract_touch` | engineer review at `yad-engineer-review` |
 | `checks` | `checks` (`pass`\|`fail`) | the gate run itself (objective) |
 
 **Deriving the provisional verdict** (build plan Step A; extended for `spec`/`tasks` in Phase 4b — the

package/skills/yad-implement/SKILL.md

@@ -124,7 +124,7 @@ finalize a `tasks` trust entry, anchored to what the human/dev actually did with
 Append the entry to `epics/<epic>/.sdlc/trust-log.json` (schema:
 `../yad-epic/references/state-schema.md`). `tasks` stays `human_approve` until its slice clears
 the threshold — this only *gathers* evidence. (The `implement` step's own verdict is finalized later,
-at the engineer review in `yad-ship`: merged as authored → `approved-unchanged`; edited first →
+at the engineer review in `yad-engineer-review`: merged as authored → `approved-unchanged`; edited first →
 `approved-with-edits`; scope/contract/checks halt → `rejected`.)
 
 ## Hard rules (build plan §B, Cross-cutting)

package/skills/yad-implement/references/implement-conventions.md

@@ -59,7 +59,7 @@ Co-Authored-By: CodeRabbit <noreply@coderabbit.ai>
 
 - Choose the entry whose `id` matches the tool that actually helped author the diff; add more than one
   line if several did. CodeRabbit is a co-author only when it **contributed code**, not when it merely
-  reviewed (that is `ai_review` in `yad-ship`).
+  reviewed (that is `ai_review` in `yad-engineer-review`).
 - For a fully human-authored commit, pick `id: none` — i.e. **omit** the trailer. `ai_coauthor.required`
   is `false`, so a missing trailer is valid and no gate fails on it.
 - `yad-implement` installs the `.gitmessage` template (`templates/.gitmessage`) and sets

package/skills/yad-open-pr/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: yad-open-pr
+description: 'Build-half helper of the gated SDLC. Open a code-repo task PR/MR from the committed platform template — detect GitHub/GitLab, push the current task branch, and create the PR/MR with the template body prefilled (Summary / Story-task / Impact & Risk) and the title defaulting to the commit subject. Auto-assigns from the hub roster: assignee = the committer, reviewers = the repo''s reviewers + domain-owners. High risk / contract surface routes to domain owners (risk-route.sh). Drives the `yad open-pr` CLI; never merges. Use when the user says "open the PR", "open the MR", or "raise the merge request".'
+---
+
+# SDLC — Open Task PR/MR (build-half helper)
+
+**Goal:** Open the PR/MR for the current task branch from the repo's committed PR/MR template
+(installed by `yad-pr-template`, Step D), with the body prefilled and the right reviewers requested.
+This is the standalone open-PR step; it **never merges** — the engineer review (`yad-engineer-review`,
+Step E) owns the merge. Distinct from `yad gate open`, which opens a front-half artifact-review PR on
+the product hub.
+
+## Conventions
+
+- Run **inside the code repo** under `{project-root}/demo-repos/<repo>/` (or pass `--repo <name>` to
+  resolve it from `.sdlc/repos.json`). The branch must be the task branch, not the default branch.
+- **Platform** is detected from the `origin` remote (or the registry / `--platform`).
+- **Title** — defaults to the last commit subject (one atomic task = one branch = one PR/MR), so it
+  follows the same Conventional-Commits style and passes the `pr-title` gate. Override with `--title`.
+- **Body** — the committed template (`.github/pull_request_template.md` /
+  `.gitlab/merge_request_templates/Default.md`) with `Task:`, `Risk level:`, `Contract surface
+  touched:`, and `Domains` prefilled; the rest is left for the author. This satisfies the `pr-template`
+  gate.
+- **Auto-assign** — from the hub roster scoped to this repo: assignee = the committer (resolved from
+  the local git identity), reviewers = the repo's `reviewer`/`domain-owner` logins minus the committer.
+  Degrades cleanly when there is no roster.
+- **Routing** — `low`/`medium` → base rule (owner + 1 reviewer); `high` (or a touched
+  contract/auth/payments surface) → plus one domain-owner per touched domain. `bash
+  checks/risk-route.sh <body>` prints the required reviewers.
+
+## Inputs
+
+- `repo`           — target a registered repo by name (optional; else the current dir).
+- `risk`           — `low|medium|high` (default `low`); prefilled into the body.
+- `contractChange` — flag; marks the contract surface touched and triggers escalation.
+- `base` / `platform` / `title` — optional overrides.
+
+## On Activation
+
+### Step 1 — Confirm the branch and template
+Confirm you are on the task branch (not the default branch) and that the PR/MR template is committed
+(if not, run `yad-pr-template` first). The branch's commits should already carry the `Task:` trailer.
+
+### Step 2 — Open the PR/MR
+Run from the repo root:
+```
+yad open-pr [--repo <name>] [--risk <level>] [--contract-change] [--title "<subject>"]
+```
+The CLI pushes the branch (sets upstream, the user's own auth), fills the template, and creates the
+PR/MR with the auto-assigned assignee + reviewers.
+
+### Step 3 — Route the review (if escalated)
+On `high` risk or a contract touch, run `bash checks/risk-route.sh <pr-body>` to print the required
+domain-owner reviewers — the same escalation `yad-engineer-review` enforces.
+
+### Step 4 — Stop (no merge)
+Report the PR/MR URL and the requested reviewers. The PR now runs the check gates (Step C); the human
+engineer review and merge happen in `yad-engineer-review` (Step E).
+
+## Hard rules
+
+- **One task = one branch = one PR/MR.** Never open a PR from the default branch.
+- **Title follows the commit subject** — Conventional-Commits style, so the `pr-title` gate passes.
+- **High risk routes to domain owners** — the same escalation as the gate; never a separate rule.
+- **Opening a PR never merges.** The human owns the merge in Step E.
+
+## Reference
+- The PR/MR template + the Impact & Risk block + routing: `../yad-pr-template/references/risk-routing.md`.
+- The gates the PR must pass: `../yad-checks/references/check-gates.md` (incl. `pr-title`, `pr-template`).
+- Commit first: `../yad-commit/SKILL.md`; commit + open in one step: `../yad-ship/SKILL.md`.
+- The engineer review + merge that follow: `../yad-engineer-review/SKILL.md`.