yadflow 2.5.0 → 2.7.0

package/skills/yad-docs-sync/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: yad-docs-sync
+description: 'The maintenance/CI reconciler for the generated docs sites — mirroring the `yad check` / `yad gate ci` drift pattern. Recomputes each site''s freshness hashes (per-epic: the artifact hash + repo HEADs; overview: config.yaml + module-help.csv + the overview diagram + skill count) and compares them to each docs-build.json baseline: a site is stale when any hash differs or its shell template is out of date. `--check` (default, read-only) reports which sites are stale and WHY; `--refresh` regenerates + redeploys each stale site; `--wire` commits the CI workflow that runs the check on push and rebuilds on staleness. Refresh is always a human/CI decision, never silent; docs are never a gate. Use when the user says "sync the docs", "check docs staleness", "refresh stale docs sites", or "wire the docs CI".'
+---
+
+# SDLC — Sync the Docs Sites (the staleness reconciler)
+
+**Goal:** Keep the generated docs sites in step with the artifacts they render — the per-epic sites
+(`epics/EP-<slug>/docs-site/`) and the project overview (`docs/sdlc-site/`). It mirrors the `yad check`
+/ `yad gate ci` reconcile pattern: it does **not** re-author content; it **detects drift** between each
+site's `docs-build.json` baseline and the current inputs, and reports / refreshes / wires CI accordingly.
+
+Docs are an output enrichment, so this skill is **never a gate** — it never touches `state.json`,
+approvals, or the contract lock. Refreshing a stale site is always a **human or CI decision**, never
+silent (the same discipline as `yad repo refresh`).
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory (the **product hub**).
+- Per-epic baseline: `epics/EP-<slug>/.sdlc/docs-build.json` (written by `yad-docs`). Overview baseline:
+  `docs/sdlc-site/.docs-build.json` (written by `yad-docs-overview`).
+- The hashing + build + deploy is the **`yad docs sync` CLI**'s job; the regeneration of a stale site is
+  delegated back to `yad-docs` / `yad-docs-overview` (the AI generation step). This skill orchestrates
+  the reconcile.
+- The docs target is `.sdlc/docs.json` (`yad-connect-docs`).
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## Inputs
+
+- `action` — `check` (default, read-only) | `refresh` | `wire`.
+- `epic` — optional. Default: **sweep all epics** under `epics/` **plus the overview**. Given an
+  `EP-<slug>`, scope to that one site.
+
+## On Activation
+
+### Step 1 — Compute the current freshness hashes per target
+For each target in scope, recompute its hash inputs (exact inputs in `references/staleness.md`):
+
+- **Per-epic** (`epics/EP-<slug>/`): the `artifactHash` (sha256 of `epic.md` + `architecture.md` +
+  `contract.md` CONTRACT-SURFACE + `ui-design.md` + each story) **and** `repoHeads` (current
+  `git -C <path> rev-parse HEAD` for each repo in `epic.repos`).
+- **Overview** (`docs/sdlc-site/`): sha256 of `skills/sdlc/config.yaml` + `skills/sdlc/module-help.csv`
+  + `docs/diagrams/sdlc-overview.mmd` + the current `skillCount` (number of `yad-*` skills).
+
+This is the same drift computation `yad check` runs for repos; reuse the repos.json HEAD-sha rule.
+
+### Step 2 — Compare to each build manifest
+Read each `docs-build.json` and compare. A site is **stale** when **any** of:
+- its `artifactHash` differs (a rendered artifact moved), or
+- any `repoHeads[<repo>]` differs from the repo's current HEAD (the code the components cite advanced —
+  the same head-sha staleness as `repos.json`), or
+- for the overview, `config.yaml` / `module-help.csv` / the `.mmd` / `skillCount` moved, or
+- its `templateVersion` < the current shell template version (the shell was upgraded).
+
+A missing `docs-build.json` (a site never generated) counts as **stale → needs generate**.
+
+### Step 3 — Act on `action`
+- **`check`** (default, **read-only**) — print which sites are stale and **WHY**, in `yad check` drift
+  style: *which artifact moved* (name it), *which repo HEAD advanced* (`<repo>: <old>→<new>`), *config /
+  manifest / diagram / skill-count changed*, or *shell upgraded* (`templateVersion`). Writes nothing.
+- **`refresh`** — for each stale site, re-run the generator (`yad-docs` for an epic site, `yad-docs-overview`
+  for the overview) to regenerate `src/data/*.ts` + theme + manifest, then redeploy via `yad docs deploy`
+  (degrading to build-only when no platform CLI). Report every site refreshed. **Never silent** — refresh
+  is a deliberate human/CI act, surfaced exactly like `yad repo refresh`.
+- **`wire`** — commit the CI workflow (Step 4) that automates the check + rebuild.
+
+### Step 4 — `wire`: the CI auto-rebuild workflow
+Commit the platform-matched workflow (GitHub `.github/workflows/yad-docs.yml`, or a GitLab `pages` job at
+`.gitlab/ci/yad-docs.yml` that must be `include:`d from the root `.gitlab-ci.yml` —
+`include: { local: .gitlab/ci/yad-docs.yml }`, the same fragment+include shape as the `yad-checks` gates):
+- on push, run **`yad docs sync --check`**; on detected staleness, **rebuild + deploy** the affected
+  site(s);
+- carry **`[skip ci]`** on any commit the workflow itself makes (the regenerated source / manifest) and
+  a **concurrency group** (one docs deploy at a time) — both to **prevent deploy loops** (a rebuild must
+  not retrigger the workflow). See `references/staleness.md`.
+
+### Step 5 — Report
+Report per target: **fresh** or **stale (why)**; for `refresh`, what was regenerated + the deploy URL or
+"build-only"; for `wire`, the workflow path committed. Never advance any epic; docs are not a gate.
+
+## Hard rules
+
+- **Refresh is never silent.** A stale site is *reported*; regenerating + redeploying is a human or CI
+  decision (the `yad repo refresh` discipline). `check` is strictly read-only.
+- **Docs are never a gate.** This skill never touches `state.json`, `approvals.json`, or
+  `contract-lock.json`. Staleness blocks nothing in the SDLC; it only flags out-of-date docs.
+- **HEAD-sha staleness, reused.** Repo drift uses the exact `repos.json` `syncedHead`-vs-current-HEAD
+  rule. The overview uses config + manifest + diagram + skill-count.
+- **Loop-prevention is mandatory in CI.** The wired workflow must carry `[skip ci]` on its own commits
+  and a concurrency group so a deploy never retriggers a deploy.
+- **Reconcile, don't re-author.** This skill detects drift and delegates regeneration to `yad-docs` /
+  `yad-docs-overview`; it does not generate `src/data/*.ts` itself.
+
+## Reference
+- The manifest schema (per-epic + overview), the exact hash inputs, the head-sha staleness rule, and the
+  CI loop-prevention note: `references/staleness.md`.
+- The generators this delegates to: `../yad-docs/SKILL.md`, `../yad-docs-overview/SKILL.md`.
+- The docs target it deploys to: `../yad-connect-docs/SKILL.md`.
+- The drift / refresh discipline this mirrors: `../yad-connect-repos/SKILL.md` (HEAD-sha staleness).

package/skills/yad-docs-sync/references/staleness.md

@@ -0,0 +1,81 @@
+# Docs staleness — manifests, hash inputs, and the CI loop note
+
+`yad-docs-sync` reconciles each generated site against a **build manifest** (`docs-build.json`) written
+when the site was last generated. A site is **stale** when the manifest's recorded hashes no longer match
+the current inputs, or its shell template is out of date. This mirrors the `repos.json`
+`syncedHead`-vs-current-HEAD drift rule used across the SDLC.
+
+## Build manifest schema
+
+### Per-epic — `epics/EP-<slug>/.sdlc/docs-build.json` (written by `yad-docs`)
+
+```json
+{
+  "builtAt": "<YYYY-MM-DD>",
+  "theme": "design.json | DESIGN.md | default",
+  "artifactHash": "<sha256 of epic.md + architecture.md + contract.md CONTRACT-SURFACE + ui-design.md + each story>",
+  "repoHeads": { "<repo>": "<HEAD sha>" },
+  "deployUrl": "<url or null>",
+  "templateVersion": "<shell template version>"
+}
+```
+
+### Overview — `docs/sdlc-site/.docs-build.json` (written by `yad-docs-overview`)
+
+```json
+{
+  "builtAt": "<YYYY-MM-DD>",
+  "theme": "yadflow-brand",
+  "artifactHash": "<sha256 of config.yaml + module-help.csv + docs/diagrams/sdlc-overview.mmd>",
+  "skillCount": <number of yad-* skills>,
+  "deployUrl": "<url or null>",
+  "templateVersion": "<shell template version>"
+}
+```
+
+## Exact hash inputs
+
+| Target | `artifactHash` inputs | head inputs |
+|--------|-----------------------|-------------|
+| **per-epic** | `epic.md` + `architecture.md` + `contract.md` **CONTRACT-SURFACE only** + `ui-design.md` + **each** `stories/*.md` (concatenated in stable story-id order, hashed sha256) | `repoHeads`: `git -C <path> rev-parse HEAD` for each repo in `epic.repos` |
+| **overview** | `skills/sdlc/config.yaml` + `skills/sdlc/module-help.csv` + `docs/diagrams/sdlc-overview.mmd`, concatenated in that order, hashed sha256 (`skillCount` is an informational manifest field, not a hash input — `module-help.csv` already moves when the skill set does) | — (no repos) |
+
+Because `yad-docs` generates `src/data/*.ts` **deterministically** (stable-ID sort, fixed key order, no
+embedded timestamps), an unchanged input set re-hashes identically — so a hash move means a *real*
+content move, not a regeneration artifact. The contract uses the **CONTRACT-SURFACE block only** so
+non-surface edits to `contract.md` don't churn the docs.
+
+## Staleness rule
+
+A site is **stale** when ANY holds:
+
+1. recomputed `artifactHash` ≠ manifest `artifactHash` — a rendered artifact moved (name it in the report);
+2. for any repo, current HEAD ≠ manifest `repoHeads[<repo>]` — the cited code advanced (`<repo>:
+   <old>→<new>`). **Identical to the `repos.json` `syncedHead` staleness rule** — and, as there, a stale
+   repo is *flagged*, never auto-refreshed: the `code-context` itself is refreshed by a human via
+   `yad repo refresh`, and the docs are regenerated only on an explicit `refresh`/CI decision;
+3. (overview) `config.yaml` / `module-help.csv` / the `.mmd` moved — the pipeline changed (this is what
+   enforces "the overview regenerates whenever the workflow definition or skill set changes"); or the
+   `templateVersion` (the yad CLI version) advanced — the doc shell upgraded;
+4. manifest `templateVersion` < the current shell template version — the `templates/app/` shell was
+   upgraded, so every site should re-copy it;
+5. the `docs-build.json` is **missing** — the site was never generated (treat as stale → generate).
+
+`check` reports which of these tripped and why; `refresh` regenerates + redeploys; neither blocks any
+SDLC step (docs are never a gate).
+
+## CI loop-prevention note
+
+The `wire` workflow (`.github/workflows/yad-docs.yml`, or the GitLab `pages` job at
+`.gitlab/ci/yad-docs.yml` included from the root `.gitlab-ci.yml`) runs
+`yad docs sync --check` on push and rebuilds + deploys on staleness. Because the rebuild **commits** the
+regenerated `src/data/*.ts` + refreshed `docs-build.json`, that commit would re-trigger the same workflow
+— a deploy loop. Two guards, both mandatory:
+
+- **`[skip ci]`** in the message of any commit the workflow itself makes (the regenerated source +
+  manifest), so the workflow does not re-fire on its own output;
+- a **concurrency group** (e.g. `concurrency: { group: yad-docs-deploy, cancel-in-progress: true }`) so
+  at most one docs build/deploy runs at a time, and a queued one is superseded rather than stacking.
+
+Together these make the CI rebuild idempotent: a push that moves an artifact deploys exactly one fresh
+site, and the resulting bot commit does not start another round.

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`.

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

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# pr-template gate.
+# The PR/MR BODY must actually USE the committed template — i.e. carry its required sections so the
+# review (and risk-route.sh) has the inputs it needs. This catches an empty / free-form description
+# that bypassed the template.
+#   --profile code (default) — the code-repo task template (yad-pr-template templates/<platform>/):
+#     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.
+# 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
+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 [pr-template]: unknown --profile '$PROFILE' (code|hub)."; exit 1 ;; esac
+
+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."
+  exit 1
+fi
+
+rc=0
+require_heading() {
+  if ! grep -qiE "^[[:space:]]*$1[[:space:]]*$" "$BODY"; then
+    echo "FAIL [pr-template]: missing section '${2}' — the PR/MR body does not use the template."
+    rc=1
+  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
+  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>).
+  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)"
+  if [ -z "$rl" ]; then
+    echo "FAIL [pr-template]: 'Risk level:' missing or not set to low|medium|high."
+    rc=1
+  fi
+fi
+
+[ "$rc" = 0 ] && echo "PASS [pr-template]: body uses the ${PROFILE} template (required sections present)."
+exit "$rc"

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

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# pr-title gate.
+# The PR/MR TITLE must follow the convention for its repo kind:
+#   --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). 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).
+# 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
+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 [pr-title]: unknown --profile '$PROFILE' (code|hub)."; exit 1 ;; esac
+
+TITLE="${ARGS[0]:-}"
+if [ -z "$TITLE" ]; then
+  echo "FAIL [pr-title]: empty title — pass the PR/MR title as the argument."
+  exit 1
+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
+  fi
+  echo "FAIL [pr-title]: '${TITLE}' is not a hub review title 'review: <artifact> (EP-<slug>)'."
+  exit 1
+fi
+
+# 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
+fi
+echo "PASS [pr-title]: '${TITLE}' (profile: code)"

package/skills/yad-run/SKILL.md

@@ -70,7 +70,7 @@ Walk the steps for `repo` starting at `from`/`currentStep`. For each step:
      the next step, and **continue the loop** (this is the Step B auto-advance for `checks`).
    - else (**`human_approve`**) → set the step `done`/`in_review`, **stop** and report
      "waiting for a human at `<next-step>`".
-5. **Always stop at `engineer-review`** (it is `locked`): hand off to `yad-ship` for the human merge
+5. **Always stop at `engineer-review`** (it is `locked`): hand off to `yad-engineer-review` for the human merge
    gate, which finalizes the trust verdict (confirm/override the provisional one).
 
 ### `action: set-dial` — earn (or revert) a step's automation
@@ -106,4 +106,4 @@ reversible (build plan §Safety). Report the new state and that `yad-status` wil
 - The loop, the trust-verdict derivation, and the threshold predicate: `references/run-loop.md`.
 - State/trust schemas: `../yad-epic/references/state-schema.md`.
 - The steps it drives: `../yad-spec/`, `../yad-implement/`, `../yad-checks/`; the human gate it
-  hands off to: `../yad-ship/`.
+  hands off to: `../yad-engineer-review/`.

package/skills/yad-run/references/run-loop.md

@@ -14,7 +14,7 @@ spec → tasks → implement → checks → engineer-review(locked)
 
 `spec` and `tasks` are the two legs of `yad-spec` (the heavy ceremony, then the atomic `tasks.md`).
 `implement` is one atomic task via `yad-implement`. `checks` is `yad-checks (action: run)`.
-`engineer-review` is the human gate at `yad-ship` — always a stop, never automated.
+`engineer-review` is the human gate at `yad-engineer-review` — always a stop, never automated.
 
 ## The loop (pseudocode)
 
@@ -40,7 +40,7 @@ while step is a back step (not engineer-review):
     else:  # human_approve
         bs.step.status = "done"; persist; STOP and report "waiting for human at <next>"
 
-# reached engineer-review: always stop, hand to yad-ship (human gate, finalizes the verdict)
+# reached engineer-review: always stop, hand to yad-engineer-review (human gate, finalizes the verdict)
 ```
 
 `ranBy` is `machine` when the *previous* step's effective dial caused this step to run without a human
@@ -62,7 +62,7 @@ per-step dial says. `engineer-review` and the five front states are covered by `
 ## Deriving signals & the provisional verdict
 
 `signals` are the raw facts of the run; the **provisional `verdict`** is derived from them. The human
-gate for each step (the engineer review at `yad-ship` for `implement`; spec acceptance for `spec`;
+gate for each step (the engineer review at `yad-engineer-review` for `implement`; spec acceptance for `spec`;
 first-consume for `tasks`; the gate itself for `checks`) later confirms or overrides the verdict and
 finalizes the entry — a human always has the last word on the trust signal.
 
@@ -114,7 +114,7 @@ Reverting (`to: human_approve`) is never gated — automation must be reversible
 
 ## What stays human, always
 
-- `engineer-review` — the merge gate. `yad-run` always stops here and hands to `yad-ship`.
+- `engineer-review` — the merge gate. `yad-run` always stops here and hands to `yad-engineer-review`.
 - The five front states (`epic`, `architecture`, `ui-design`, `stories`, `test-cases`) — not in
   `back_steps`, in `locked_steps`; the dial-setter refuses them.
 - Any contract-surface change — halts the loop and routes back to the architecture gate, regardless of