yadflow 3.0.0 → 3.2.0

package/skills/yad-connect-repos/references/hub-config.md

@@ -19,6 +19,7 @@ login to an SDLC name + role. It is a single object for the hub itself — the s
   "git_url": "https://github.com/abdelrahmannasr/yadflow.git",
   "default_branch": "main",
   "bridge_enabled": true,                                     // open review PRs/MRs on the hub for front-half reviews
+  "review": { "requireEngagement": false },                   // Review Companion: false (soft) counts bare approves but nudges; true counts only verified-engagement approvals
   "detectedAt": "2026-06-08",                                 // last detect-hub run (YYYY-MM-DD)
   "roster": [
     { "login": "abdelrahmannasr", "name": "alice", "email": "alice@example.com",
@@ -76,6 +77,15 @@ as the registry). `detect-hub` upserts `hub.json` in place — it is idempotent
   existing **file-only** flow with no error. The file ledger is the source of truth in both modes.
 - The master switch `config.yaml` `hub.bridge: false` disables the bridge globally regardless of `hub.json`.
 
+## Review Companion engagement (`review.requireEngagement`)
+
+`review.requireEngagement` (default `false`) controls the [Review Companion](../../yad-review-companion/SKILL.md)
+engagement gate. Each approval records `engagement: verified | none`. **Soft (`false`):** both count — a
+bare approve still passes but draws a friendly public nudge, so review *quality* is visible without
+blocking. **Strict (`true`):** the predicate counts only `verified` approvals. The signal is gameable by
+design ("visible, not impossible") — it raises the cost of a rubber-stamp, it does not prove a human
+read the artifact. Applies to both the front gate and the back-half engineer review.
+
 ## Git tracking
 
 Commit `hub.json` — it is small, reviewable, and carries no secrets (logins and names only, never tokens).

package/skills/yad-docs-overview/references/pipeline-model.md

@@ -56,6 +56,7 @@ The gated authoring chain + the reusable review gate (10 steps, or 12 with the o
 | `yad-stories` | → `stories-review` (per-repo routing) | `stories/EP-<slug>-S0N.md` |
 | `yad-test-cases` | → `test-cases-review` (parallel, non-blocking) | `test-cases.md`, `test-links.json` |
 | `yad-review-gate` | the shared gate | `reviews/*.md`, `approvals.json`, `comments.json` |
+| `yad-review-companion` | the fun/visible review layer (trailer/cards/chat + engagement) | `approvals.json` `engagement`, platform trailer/cards |
 | `yad-hub-bridge` | the platform PR/MR bridge | `hub-prs.json` |
 
 ### Path: Build half (`phase: 3-build`)

package/skills/yad-engineer-review/SKILL.md

@@ -39,11 +39,29 @@ a **second set of eyes, never the authority**: it cannot approve or merge. Where
 (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.
 
+Also run the **Review Companion** so the human review is easy and fun: post the 60-sec trailer
+(`yad review trailer --repo <r> --pr <n> --body "<text>"`) and deal the swipe cards / open the grounded
+chat from the bundle (`yad review context --repo <r> --pr <n>` → [yad-review-companion](../yad-review-companion/SKILL.md)).
+Companion comments carry `<!-- yad:noblock -->` (history-only, never block); genuine concerns are posted
+unflagged and block normally.
+
+For a **deep, teaching** review instead of a skim, offer the **Pair Review** walkthrough
+([yad-pair-review](../yad-pair-review/SKILL.md)): `yad review walkthrough --repo <r> --pr <n>` deals an
+ordered, risk-tagged stop-list, and the AI walks the engineer through the change one stop at a time —
+asking questions, answering theirs, until both are satisfied — then records the engineer's review-skill
+growth in the local-only learning log. Still soft: it rides the same `engagement: verified` signal and
+never gates. When a pair session backs the approve, you may set `companion.pair: true` on the ship record.
+
 ### 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.
+Record `engagement: verified` when the engineer reviewed through the companion (else `none` for a bare
+approve); `yad review reconcile --epic <id> --repo <r> --pr <n>` stamps it onto the ship record from the
+platform. Soft by default (both count; a bare approve draws `yad review nudge`); only gates when
+`hub.review.requireEngagement: true`. The signal is gameable by design and sits **beside** the CI gates,
+never above them.
 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.
 
@@ -55,8 +73,8 @@ engineer-review rule is satisfied (Step 2). Then:
   ```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>" }
+    "ai_review": "coderabbit (advisory)", "engineer_review": [{"approver":"<name>","role":"<role>","domain":"<opt>","engagement":"<verified|none>"}],
+    "companion": {"trailer":true,"cards":true,"chat":false}, "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

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

@@ -33,9 +33,10 @@ Append-only. One record per shipped task:
       "gates": ["spec-link", "contract-check", "build-test-lint"],
       "ai_review": "coderabbit (advisory)",
       "engineer_review": [
-        { "approver": "amelia", "role": "owner" },
-        { "approver": "carol", "role": "reviewer" }
+        { "approver": "amelia", "role": "owner", "engagement": "verified" },
+        { "approver": "carol", "role": "reviewer", "engagement": "none" }
       ],
+      "companion": { "trailer": true, "cards": true, "chat": false },
       "risk": "low",
       "shippedAt": "2026-06-06"
     }
@@ -46,6 +47,18 @@ Append-only. One record per shipped task:
 This is the back-half analogue of the front half's `approvals.json` — files only, no hidden state, so a
 future service can drive ship by writing the same records.
 
+**Engagement (the Review Companion).** Each `engineer_review` entry carries `engagement: verified | none`
+— `verified` when the engineer reviewed through the [companion](../../yad-review-companion/SKILL.md)
+(`yad review trailer/context/nudge`, a real trailer/cards/chat session over the diff), `none` for a bare
+approve. The optional `companion` block records which faces ran. It is **soft by default** (both count;
+a bare approve draws a friendly `yad review nudge`); it only gates ship when
+`hub.review.requireEngagement: true`. `yad review reconcile --epic <id> --repo <r> --pr <n>` reads the
+code PR's approvals (with the engagement signal) and stamps them onto the matching ship record — the
+back-half **bridge**, the analogue of `yad gate sync`. The signal is gameable by design ("visible, not
+impossible"): it makes engineer-review quality visible, it does not prove a human read the diff. It sits
+**beside** the CI gates (build/test/lint/contract/verified-commits) — never above them; CI still
+decides machine safety, the merge is still the human act.
+
 ## Story state
 
 The story frontmatter `status` reflects build progress:

package/skills/yad-hub-bridge/references/bridge.md

@@ -35,6 +35,40 @@ glab api projects/:id/merge_requests/:iid/notes          # discussion notes (com
 All commands run as the **local user**; the bridge stores no tokens. If the CLI is missing/unauthenticated
 or the remote is unreachable, the bridge stops and the gate falls back to file-only (no error).
 
+> **GitLab read parity (GAP-6).** `readPrGitLab` reads approvals (`approved_by[]`) and discussions but
+> does **not** map a "Request changes" reviewer state to `CHANGES_REQUESTED` — on GitLab the blocking
+> signal is an **unresolved discussion**. So on GitLab the gate is held by unresolved threads, not by a
+> reviewer state. (GitHub maps both.) If you need GitLab "Request changes" honored, read
+> `reviewers[].state` from the MR and map it to `CHANGES_REQUESTED`.
+
+## Open recipes (request the reviewers — used by `yad gate open` / `yad open-pr`)
+
+Opening the review PR/MR must **request the required reviewers**, or an escalated gate is opened with
+nobody asked. The CLI (`createPr` in `cli/platform.mjs`) does this; an agent opening a PR by hand uses:
+
+**GitHub** — create, then add each reviewer (a bad/non-collaborator login WARNS instead of aborting the
+whole create):
+```bash
+gh pr create --title "review: <artifact> (<epic>)" --body <body> --base <default> --head <branch> \
+  --assignee @me --label domain:<repo>
+gh pr edit <n> --add-reviewer <login>      # once per required reviewer
+```
+
+**GitLab** — a Free/Core MR carries a **single** reviewer field (multiple reviewers is Premium), so
+assign the first required reviewer and **@-mention the rest in a note** so they are still notified/routed:
+```bash
+glab mr create --title "review: <artifact> (<epic>)" --description <body> \
+  --target-branch <default> --source-branch <branch> --reviewer <first-login> --label domain:<repo> --yes
+glab mr note <iid> -m "Review requested (owner + reviewer rule): @<l2> @<l3> — please review and approve/comment on this MR (this drives the gate)."
+```
+The read side counts a mentioned reviewer normally: their eventual **approval** still appears in
+`…/approvals → approved_by[]`, and their **note** in `…/discussions` — so the single-reviewer-field cap
+loses only the native "Reviewers" UI chip, not the gate routing.
+
+Required reviewers = the hub's `reviewer`/`domain-owner` roster logins for the touched scopes, PLUS any
+repo whose ownership lives only in `repos.json` `domain_owner`/`domain_owners` (those are resolved to a
+login and requested too — otherwise an escalated step is structurally unsatisfiable through routing).
+
 ## Login → role resolution (order)
 
 1. Roster (`.sdlc/hub.json`) maps `login` → `name` + base `role` (owner/reviewer).

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

@@ -62,6 +62,16 @@ PR/MR with the auto-assigned assignee + reviewers.
 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 3b — Post the review trailer (optional, recommended)
+Make the reviewer's job easy: generate the 60-sec briefing and post it to the new PR/MR so it greets
+every reviewer in the UI (idempotent; safe to re-run after a push):
+```bash
+yad review trailer --repo <name> --pr <n> --body "<companion-generated briefing>"
+```
+The full fun-review flow (cards + grounded chat + engagement) is driven by the
+[Review Companion](../yad-review-companion/SKILL.md) during `yad-engineer-review`. Non-blocking by
+design — companion comments carry `<!-- yad:noblock -->`.
+
 ### 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).

package/skills/yad-pair-review/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: yad-pair-review
+description: 'The guided, two-way, teaching pair-review walkthrough for the SDLC review gates — the AI-driven companion face. The human opens a PR/MR with an AI session and the AI walks them through the change ONE STOP AT A TIME (highest-risk first), giving comprehensive context per change, then asking the human a Socratic question about it; the human answers and asks back, and both keep going until BOTH declare satisfied. The session doubles as a learning session: it demonstrates a transferable review method, scores the engineer against it, and records their review-skill growth in the local-only yad-learn ledger (rolled up by yad status). Works on the back-half code PR/MR (yad review) and the front-half artifact-review PR/MR (yad gate). Soft and additive — it NEVER blocks a merge or gate; it rides the existing engagement signal and surfaces genuine concerns as normal blocking comments. Use when the user says "pair review this", "walk me through the PR/MR", "review with me", "co-review", or "teach me to review".'
+---
+
+# SDLC — Pair Review (the guided, two-way, teaching walkthrough)
+
+**Goal:** turn a review from a solo skim into a **paired session** where the AI is the senior reviewer
+sitting beside a junior engineer. The AI **drives** the review change-by-change, explains each change in
+depth, then **asks the human about it** (flipping the companion's chat direction); the human answers and
+asks back; both keep answering **until both are satisfied**. The PR is the textbook, the walkthrough is
+the lesson — and the engineer walks away having *learned how to review a PR efficiently*, with that
+growth recorded in their personal learning log.
+
+This is the **fifth face** of the Review Companion — the AI-driven, bidirectional, teaching layer on top
+of [`yad-review-companion`](../yad-review-companion/SKILL.md) (Trailer / Cards / Chat / Social). The
+**gate still owns the predicate and advancement**; this skill only enriches the *input* and records the
+*engagement* + *learning* signals. Like the companion, **the CLI never calls an LLM — you (this skill)
+generate every briefing, question, and answer, grounded only in real material, and post via the
+platform.**
+
+> **Philosophy — "the review is the lesson, and laziness stays visible, not blocked."** Every signal here
+> is soft and gameable by design (same as the companion + learning layers). A pair session never proves a
+> human understood anything and never holds the gate; it makes a real review the *easiest, most useful*
+> path and turns it into mentorship. Say this openly — do not oversell it.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory — the **product hub**.
+- Back half (code PR/MR): grounded by `yad review walkthrough --repo <r> --pr <n>`.
+- Front half (artifact-review PR/MR): grounded by `yad gate walkthrough <epic> [artifact]`.
+- The transferable review method + scorecard live in `references/review-rubric.md`.
+- The session-record comment shape, the dual sign-off, and the learning record this writes live in
+  `references/session-state.md` (it reuses [`yad-learn`](../yad-learn/SKILL.md)'s ledger + gitignore
+  discipline **verbatim** — the learning output is **local-only, never committed or pushed**).
+- Speak in the configured `communication_language`; write any rendered tutorial in
+  `document_output_language`.
+
+## Inputs
+
+- Back half: `repo` + `pr`. Front half: `epic` + `artifact`.
+- `member` — the learner being paired with (default: the invoking user). Used for the learning record.
+- `action` — `walkthrough` (the full session, default) | `record` (just write the session comment +
+  learning record from an already-finished session) | `rubric` (print the review method and stop).
+
+## On Activation (`action: walkthrough`)
+
+### Step 1 — Get the ordered stops (the grounding)
+Run the walkthrough grounding for the half you're on:
+- Back half: `yad review walkthrough --repo <r> --pr <n>` → prints the grounding bundle **plus an ordered
+  `stops[]`** (the code diff parsed into hunk-anchored, risk-tagged review stops, highest-risk first).
+- Front half: `yad gate walkthrough <epic> [artifact]` → the same, over the artifact's review diff.
+
+**Read the real material yourself** — run the bundle's `diffCmd`, and read the named `codeMap` / `pack` /
+`contract` / `artifactPath` / `specs/<story>/` files. Never invent content. If a stop's material isn't
+available, say so at that stop (a gap is a finding — see Hard rules).
+
+### Step 2 — Set the frame (teach the method first)
+Briefly state the **review method** you'll both follow (from `references/review-rubric.md`): spec-first →
+contract-surface → high-risk hunks first → per-change correctness · tests · edge cases · security/auth/
+payments → tests-cover-the-change → decide. Tell the human you'll walk the change in that order and ask
+them to apply each step with you. This framing is the lesson scaffold.
+
+### Step 3 — Walk the stops, one at a time (the two-way loop)
+For **each stop in `stops[]` order** (highest-risk first):
+1. **Comprehensive briefing.** Explain *what* changed in this hunk, *why* (tie it to the spec / epic /
+   contract), *how it fits* the surrounding code (use the code-map), and *where the risk is* (call out the
+   stop's `riskTags` — `contract`/`auth`/`payments`/`tests`). Cite real file + line ranges.
+2. **Socratic question.** Ask the human ONE focused question that applies a rubric step to *this* change —
+   e.g. "this touches the `auth` surface — what could a malicious caller do here, and does the change
+   guard it?" or "which test covers this branch, and what edge case is still uncovered?"
+3. **Two-way until satisfied with the stop.** The human answers and may ask their own questions; you
+   answer **only from real material**, citing lines. Coach — if they miss a rubric angle, surface it and
+   explain *how* an efficient reviewer would have caught it. The stop closes when **both** of you are
+   satisfied with it (no open concern, the human has engaged the change).
+4. **Capture the moment** for the scorecard: which rubric step this stop exercised, and whether the human
+   nailed it, needed a nudge, or missed it (feeds the learning `comprehension` signal).
+
+A **genuine concern** found at any stop (a real bug, a missing test, an unguarded surface) is posted as a
+**normal, unflagged** PR/MR comment so it **blocks** like any reviewer's note — exactly the companion
+rule. Do not bury a real finding inside the session log.
+
+### Step 4 — Dual sign-off (both satisfied)
+After the last stop:
+- **AI sign-off (your verdict).** State plainly: did the human demonstrate understanding across the
+  rubric? Are there any unresolved blocking concerns? "Satisfied" from you means *no unresolved blocking
+  concern remains*.
+- **Human sign-off.** The human decides: **approve** or **request changes**. When they approve through
+  this session, submit the approval carrying the engagement marker so the gate records
+  `engagement: verified` — back half: `gh pr review <n> --approve --body "<note>\n\n<!-- yad:engagement verified -->"`
+  (GitLab: `glab mr approve <n>` then a note with the marker); front half: the human approves via
+  [`yad-review-gate`](../yad-review-gate/SKILL.md) the normal way.
+
+"**Both satisfied**" = the human approved **and** your verdict holds no unresolved blocking concern. If
+either is not satisfied, the loop continues (more stops, or the human requests changes and the owner
+addresses them) — nothing advances on a half-finished session.
+
+### Step 5 — Record the session (twice) — see `references/session-state.md`
+1. **Session comment (PR/MR history).** Post one comment built by the CLI helper `pairSessionBody`
+   (carries `<!-- yad:pair -->` so `yad status` can count paired reviews, and `<!-- yad:noblock -->` so it
+   never holds the gate): the transcript summary, the **review-skill scorecard**, your AI verdict, and
+   both sign-offs. Post it with the platform CLI (`gh pr comment` / `glab mr note`).
+2. **Learning record (local-only).** Append a `yad-learn` record for the `member`: `concept` =
+   `review <repo> PR #<n> — <title>` (front half: `review <artifact> (<epic>)`), `stage` =
+   `engineer-review` (back) / `<artifact>-review` (front), `mode` = `deep` (or `quiz` when you scored
+   comprehension), `comprehension` = the scorecard roll-up, `tutorial` = a rendered
+   `learning/<member>--review-<pr>.md` capturing the method as applied to this PR + the engineer's gaps.
+   **First ensure the hub `.gitignore` covers the learning paths** (reuse yad-learn's guard), then write —
+   these are personal, gitignored, **never committed or pushed**. The growth rolls up under `yad status`
+   "My skills".
+
+## Hard rules
+
+- **Never a gate.** This skill never moves `currentStep`, never records an approval on the human's
+  behalf, and never merges. It enriches the input and rides the existing soft `engagement` signal only.
+  Strict mode (`hub.review.requireEngagement`) is the gate's switch, not this skill's.
+- **The CLI never calls an LLM.** The sequencer (`stops[]`) and the markers are deterministic; *you*
+  generate every briefing, question, and answer. Same split as the companion.
+- **Grounded only in real material.** Briefings/answers come from the diff + artifact + contract +
+  code-map/pack + specs. If the material can't answer something, **say so — that gap is itself a finding**
+  and is posted as a genuine, blocking comment, not fabricated over.
+- **Real concerns block; the session log never does.** Genuine findings are posted **unflagged**; the
+  session comment carries `<!-- yad:pair -->` + `<!-- yad:noblock -->` and is permanent history only.
+- **The learning output is local-only.** Reuse yad-learn's gitignore guard before writing; never commit
+  or push the records/tutorials, and never write them into a code repo.
+- **You never approve for the human and never merge.** You pair and teach; the human acts.
+
+## File-only mode (no platform)
+
+With no hub platform there is no PR to post to: write the session record to
+`reviews/<base>--<date>--pair-session.md` alongside the existing `reviews/*.md`, and the human records
+approval the manual way via [`yad-review-gate`](../yad-review-gate/SKILL.md). The learning record is
+written exactly the same (it is local-only regardless of platform). The session logic is unchanged; only
+the posting surface differs.
+
+## Reference
+
+- The transferable review method + scorecard schema: `references/review-rubric.md`.
+- The session comment shape, dual sign-off, and learning record: `references/session-state.md`.
+- The four skim faces this complements: [`yad-review-companion`](../yad-review-companion/SKILL.md).
+- The back-half merge gate it enriches: [`yad-engineer-review`](../yad-engineer-review/SKILL.md).
+- The front-half gate it enriches: [`yad-review-gate`](../yad-review-gate/SKILL.md).
+- The learning layer it records into: [`yad-learn`](../yad-learn/SKILL.md) and its
+  `references/learning-state.md`.

package/skills/yad-pair-review/references/review-rubric.md

@@ -0,0 +1,56 @@
+# The review method + scorecard (the transferable skill)
+
+This is the repeatable, efficient PR/MR review method the pair walkthrough demonstrates on the real
+change and scores the engineer against. It is **transferable** — the point is that after a few paired
+sessions the engineer reviews this way on their own. `action: rubric` prints this method and stops.
+
+## The method (the order the walkthrough follows)
+
+1. **Spec first — know what it should do.** Read the acceptance criteria / story / `specs/<story>/`
+   before the diff. You can't judge a change you can't measure against its intent.
+2. **Contract surface — did it move the locked surface?** Map the diff against the locked contract
+   (`contract.md` / `contract-lock.json`). A change to the surface without a `Contract-Change` is a
+   routing problem, not just a code problem (it must go back to the architecture gate).
+3. **Risk first — walk the dangerous hunks first.** The grounding orders stops highest-risk first
+   (`contract` > `auth`/`payments` > everything; larger hunks before smaller). Spend your attention where
+   a mistake costs the most; don't read top-to-bottom.
+4. **Per change — the four lenses.** For each hunk ask: **correctness** (does it do what the spec says,
+   including the unhappy path?), **tests** (is the new behaviour covered?), **edge cases** (nulls, empty,
+   concurrency, large input, failure/rollback), **security** (auth/authz, injection, secrets, payments
+   integrity) — weight the last two hard on `auth`/`payments`/`contract` stops.
+5. **Tests cover the change.** A `tests`-tagged stop should map to the behaviour stops. Behaviour with no
+   test is a finding; a test that doesn't exercise the new branch is a finding.
+6. **Decide — approve or request changes.** A clear verdict with the *why*. "Looks good" is not a review;
+   name what you checked and what convinced you.
+
+## The scorecard (feeds the learning signal)
+
+At each stop, capture which rubric step it exercised and how the engineer did. Roll the stops up into a
+compact scorecard for the session comment and the `comprehension` field of the learning record.
+
+Per-step grade (one of):
+
+| grade | meaning |
+|-------|---------|
+| ✅ nailed | the engineer applied the step correctly unprompted |
+| 💡 nudged | they got there after a Socratic hint — a learning moment |
+| ⚠️ missed | they didn't catch it; the AI surfaced it and explained how to next time |
+| — n/a | the step didn't apply to this change |
+
+`comprehension` for the learning record is a short roll-up, e.g. `4/6 steps nailed, 2 nudged
+(contract-surface, edge-cases)` — honest about where the engineer is still growing. It is a soft,
+gameable signal (a learning aid), never a gate — say so.
+
+## Example scorecard block (rendered into the session comment)
+
+```
+| Rubric step            | Grade   | Note                                                |
+|------------------------|---------|-----------------------------------------------------|
+| 1 Spec first           | ✅ nailed | read the AC before the diff                         |
+| 2 Contract surface     | 💡 nudged | spotted the surface change after a hint             |
+| 3 Risk first           | ✅ nailed | started on the auth hunk                            |
+| 4 Four lenses          | ⚠️ missed | missed the missing authz check on the new endpoint  |
+| 5 Tests cover          | ✅ nailed | flagged the uncovered error branch                  |
+| 6 Decide               | ✅ nailed | clear request-changes with the why                  |
+Comprehension: 4/6 nailed, 1 nudged, 1 missed (four-lenses/security)
+```

package/skills/yad-pair-review/references/session-state.md

@@ -0,0 +1,82 @@
+# The session record, the dual sign-off, and the learning record
+
+The pair walkthrough writes its outcome to **two** places, neither of which is a gate ledger and neither
+of which ever blocks the gate. The gate's predicate (approvals + resolved threads + merge) is untouched.
+
+## 1. The session comment (PR/MR platform history)
+
+Built by the CLI helper `pairSessionBody({ summary, scorecard, verdict, humanSignoff, aiSignoff })` in
+`cli/companion.mjs`. It carries **both** markers:
+
+- `<!-- yad:pair -->` — so this is countable as a *paired review* in the `yad status` 🏆 roll-up.
+- `<!-- yad:noblock -->` — so the thread is excluded from the gate's blocking check and persists as
+  permanent history (a deliberate, unresolved trail), exactly like the companion's card/chat threads.
+
+It **never** carries an engagement marker — the session comment is *history*, not the approval. The
+approval is a separate act (Step 4) and carries `<!-- yad:engagement verified -->` on its own.
+
+Sections (you generate the prose; the helper composes them):
+- **summary** — what was walked, how many stops, where the risk was, what the human engaged with.
+- **scorecard** — the rubric table + comprehension roll-up from `references/review-rubric.md`.
+- **verdict** — the AI sign-off: understanding demonstrated? any unresolved blocking concern?
+- **humanSignoff / aiSignoff** — the two satisfaction statements ("both satisfied").
+
+Post it with the platform CLI (`gh pr comment <n> -b "<body>"` / `glab mr note <n> -m "<body>"`). In
+file-only mode write it to `reviews/<base>--<date>--pair-session.md` instead.
+
+## 2. The learning record (local-only, reuses yad-learn)
+
+This is the "review **is** the lesson" half. It reuses [`yad-learn`](../../yad-learn/SKILL.md)'s ledger
+schema and gitignore discipline **verbatim** — see `yad-learn/references/learning-state.md`. Do not
+invent a new store.
+
+**Before writing anything**, ensure the **product hub's** `.gitignore` covers the learning paths
+(idempotent — append only if absent), the same block yad-learn uses:
+
+```
+# yadflow learning layer — personal, local-only (never commit or push)
+.sdlc/learning-records.json
+.sdlc/learning/
+epics/*/.sdlc/learning-records.json
+epics/*/learning/
+```
+
+Then append one record to `epics/EP-<slug>/.sdlc/learning-records.json` (or `.sdlc/learning-records.json`
+cross-project), using yad-learn's exact field shape:
+
+```json
+{
+  "member": "alice",
+  "concept": "review backend PR #42 — add refund endpoint",
+  "context": "pair-review walkthrough; risk: payments, contract",
+  "stage": "engineer-review",
+  "mode": "quiz",
+  "tool": "harness-native",
+  "sessionId": null,
+  "tutorial": "learning/alice--review-42.md",
+  "comprehension": "4/6 nailed, 1 nudged, 1 missed (four-lenses/security)",
+  "status": "learned",
+  "requestedAt": "<YYYY-MM-DD>",
+  "completedAt": "<YYYY-MM-DD>"
+}
+```
+
+Field notes:
+- `stage` = `engineer-review` (back half) or `<artifact>-review` (front half, e.g. `architecture-review`).
+- `mode` = `deep` for a walkthrough that didn't score, `quiz` when you captured a comprehension roll-up.
+- `comprehension` = the scorecard roll-up string (null when `mode: deep`).
+- `tool` = `harness-native` (or `deeptutor` if a DeepTutor session backed the tutoring).
+- `status` = `learned` once the session completed (set `completedAt`); `in-progress` if paused.
+
+Also render the tutorial artifact `epics/EP-<slug>/learning/<member>--review-<pr>.md` (front-matter:
+`member`, `concept`, `stage`, `tool`, `requestedAt`) — the review method as applied to *this* PR plus the
+engineer's specific gaps and how to close them. Both files are **local-only, gitignored, never committed
+or pushed, and never written into a code repo** — they are a private personal skills log. `yad status`
+rolls them up by stage (e.g. "engineer-review: 3").
+
+## Optional: stamp the build-log (back half)
+
+When the task later ships, [`yad-engineer-review`](../../yad-engineer-review/SKILL.md) may record on the
+ship record's `companion` block that a pair session ran: `"companion": { "trailer": true, "cards": false,
+"chat": false, "pair": true }`. This is informational only — it never changes whether the ship is
+allowed.

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

@@ -45,6 +45,15 @@ if [ -z "$BODY" ] || [ ! -f "$BODY" ]; then
   exit 1
 fi
 
+# The Review Companion injects a `<!-- yad:trailer --> … <!-- /yad:trailer -->` briefing block (and
+# `<!-- yad:noblock -->` notes) into the description. Strip those before the template check so the
+# AI-generated prose can never hide a required section heading or be mistaken for the `Risk level:`
+# value (the trailer is prepended, so an unstripped "risk level" mention would win `head -1`).
+STRIPPED="$(mktemp)"
+trap 'rm -f "$STRIPPED"' EXIT
+sed '/<!-- yad:trailer -->/,/<!-- \/yad:trailer -->/d; /<!-- yad:noblock -->/d' "$BODY" > "$STRIPPED"
+BODY="$STRIPPED"
+
 rc=0
 require_heading() {
   if ! grep -qiE "^[[:space:]]*$1[[:space:]]*$" "$BODY"; then

package/skills/yad-review-companion/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: yad-review-companion
+description: 'The fun, easy, transparent review companion for the SDLC review gates. Generates a 60-second AI "trailer" of what changed and where the risk is, deals a swipe-through deck of small review "cards", and runs a grounded chat where a reviewer asks anything and their questions become the review record — then records an engagement signal on the approval (verified vs none) and posts a friendly public nudge on a bare rubber-stamp. Works on the front-half artifact-review PR/MR (yad gate) and the back-half code PR/MR (yad review). Use when the user says "review this", "run the companion", "give me the trailer/cards", or wants reviewing to be less of a chore.'
+---
+
+# SDLC — Review Companion (fun & easy, transparent review)
+
+**Goal:** make the honest review the *easiest, most enjoyable* path, and make laziness **visible**, not
+blocked. This companion does **not** try to prove a human read something — no quiz, no un-fakeable
+proof (a quiz is answerable by AI, swipes can be spammed). Instead it removes the friction that makes
+reviewers skip, and it makes review *quality* visible to the whole team.
+
+> **Philosophy — "visible, not impossible."** Every engagement signal here is gameable by design. It
+> raises the cost of a bare rubber-stamp and shines a light on it; it never claims certainty. State that
+> openly — do not oversell it.
+
+This companion is the AI layer on top of [`yad-review-gate`](../yad-review-gate/SKILL.md) (front half)
+and [`yad-engineer-review`](../yad-engineer-review/SKILL.md) (back half). The **gate** still owns the
+predicate and advancement; the companion only enriches the *input* and records the *engagement* field.
+The CLI never calls an LLM — **you** (this skill) generate the text and post it via the platform.
+
+## The four faces
+
+1. **🎬 Trailer (A)** — a 60-second briefing: what this change does, where the risk is (from the step's
+   `risk_tags`), and an honest read-time estimate. Posted to the **PR/MR description** as a delimited
+   `<!-- yad:trailer --> … <!-- /yad:trailer -->` block so everyone sees it in the UI. Regenerated when
+   the artifact changes (it must never lie about the current content).
+2. **🃏 Cards (B)** — split the change into small **atomic claims**, one per card, each anchored to real
+   line numbers / hunks and tagged with risk. Posted as PR/MR comment threads the reviewer skims 👍/🤔.
+3. **💬 Chat (C)** — a grounded Q&A: the reviewer asks anything; you answer **only from real material**
+   (the artifact + diff + contract + the repo `code-map.md`/`pack.md` + sister docs). The reviewer's
+   questions and flagged concerns become the review record. If you **cannot** answer from the material,
+   say so — that gap is itself a finding (post it as a genuine, blocking comment).
+4. **🏆 Social (E)** — a verified-engagement mark on a real companion review, a friendly public
+   @-mention nudge on a bare approve, and light read-only gamification surfaced by `yad status`.
+
+## Markers (the contract with the gate — all live in PLATFORM data, never a ledger file)
+
+- `<!-- yad:trailer -->` / `<!-- /yad:trailer -->` — the trailer block in the PR/MR description.
+- `<!-- yad:noblock -->` — on **every** companion-posted comment (card deck, chat log) and the nudge.
+  The gate **excludes** these threads from the blocking check, so they stay unresolved as a permanent
+  PR/MR history trail and never hold the gate. A reviewer's *genuine* concern is posted **without** this
+  marker, so it blocks normally.
+- `<!-- yad:engagement verified -->` — embedded in the body of a companion-driven **Approve** review.
+  A bare UI click has no marker → `engagement: none`. (Definitions live in `cli/companion.mjs`.)
+
+## On activation
+
+Inputs: `epic` + `artifact` (front half) **or** `repo` + `pr` (back half); and the `action`
+(`trailer` | `cards` | `chat` | `approve` | `nudge`, default the full flow).
+
+1. **Get the grounding bundle.** Front half: `yad gate review <epic> [artifact]` prints JSON with the
+   artifact path, risk tags, PR number, contract path, touched domains, repo code-map paths, and
+   `requireEngagement`. Back half: `yad review chat --repo <r>` (see `yad-engineer-review`) provides the
+   diff + code-map grounding. Read the named files yourself — never invent content.
+2. **Trailer.** Generate ≤6 lines (what / risk / read-time), grounded only in the bundle. Post it:
+   `yad gate trailer <epic> <artifact> --body "<text>" [--pr <n>]` (idempotent; re-run after edits).
+3. **Cards.** Produce atomic claims, each citing real lines. Post the deck as a single comment carrying
+   `<!-- yad:noblock -->`. A reviewer's 🤔 with a real concern → re-post as a **normal, unflagged**
+   comment so it blocks.
+4. **Chat.** Answer from the material with cited lines. Append the Q&A log as a `<!-- yad:noblock -->`
+   comment so it persists in history without blocking. Turn genuine concerns into unflagged comments.
+5. **Approve.** When the reviewer is satisfied, submit an Approve whose body carries
+   `<!-- yad:engagement verified -->` (so the gate records `engagement: verified`). GitHub:
+   `gh pr review <n> --approve --body "<note>\n\n<!-- yad:engagement verified -->"`. GitLab: approve,
+   then post the marker as a note (`glab mr approve <n>` + `glab mr note <n> -m "…<!-- yad:engagement verified -->"`).
+6. **Nudge.** A bare approve (engagement `none`) still counts under the soft default; `yad gate sync`
+   posts the friendly @-mention automatically. You may also post it directly with the
+   `<!-- yad:noblock -->` marker.
+
+## Hard rules
+
+- **Never write a ledger file.** Post comments / the trailer / the approval to the PLATFORM (the
+  reviewer's own `gh`/`glab`). CI writes `approvals.json`/`comments.json`; the `ledger-guard` check
+  rejects a human ledger edit on a review PR. The markers ride in platform data only.
+- **Trailer/cards/chat are grounded ONLY in real material.** If the material does not answer a
+  question, say so and record the gap — do not fabricate.
+- **Companion comments never block; genuine concerns always do.** Flag the former with `yad:noblock`;
+  leave the latter unflagged.
+- **The engagement signal is gameable and you say so.** It makes review quality visible; it is not
+  proof. The strict-mode switch is `hub.review.requireEngagement` (off by default).
+- **The companion never approves on a human's behalf and never merges.** It assists; the human acts.
+
+## File-only mode (no platform)
+
+With no hub platform, there is no PR to post to: write the trailer to
+`reviews/<artifact-base>--<date>--trailer.md` and the card/chat notes alongside the existing
+`reviews/*.md`, and the reviewer records approval the manual way (`yad-review-gate` `approve`). The same
+generation logic applies; only the surface changes.

package/skills/yad-review-gate/SKILL.md

@@ -92,8 +92,12 @@ Repeat comment→address rounds until reviewers are satisfied. **Commenting neve
 
 **`approve`** — Record an approval. Append to `.sdlc/approvals.json`:
 ```json
-{ "artifact": "<artifact>", "step": "<step id>", "approver": "<name>", "role": "<owner|reviewer|domain-owner>", "domain": "<optional>", "status": "approved", "date": "<YYYY-MM-DD>" }
+{ "artifact": "<artifact>", "step": "<step id>", "approver": "<name>", "role": "<owner|reviewer|domain-owner>", "domain": "<optional>", "status": "approved", "date": "<YYYY-MM-DD>", "engagement": "<verified|none>" }
 ```
+`engagement` records whether the approval came through the [Review Companion](../yad-review-companion/SKILL.md)
+(a real trailer/cards/chat session = `verified`) or as a bare click (`none`). It is soft by default
+(both count; a bare approve draws a friendly nudge) and only gates when `hub.review.requireEngagement`
+is on — see `references/gating.md`. The signal is gameable by design ("visible, not impossible").
 Also write/refresh `reviews/<artifact-base>--<YYYY-MM-DD>--approved.md` as a **named roster** with three
 sections, so every participant is attributable in one place:
 

package/skills/yad-review-gate/references/gating.md

@@ -12,6 +12,15 @@ Let `A` = the set of `approved` records in `.sdlc/approvals.json` for this step.
 **Escalated pass** (step `risk_tags` ∩ `{contract, auth, payments}` ≠ ∅): base pass AND, for every
 touched `domain`, `|domainOwners[domain]| >= 1`.
 
+**Engagement (the Review Companion).** Each approval carries `engagement: verified | none` —
+`verified` when it was recorded through the companion (a real trailer/cards/chat session), `none` for a
+bare UI click. By **default (soft)** both count: a bare approve still passes the gate but is recorded
+`none` and draws a friendly public @-mention nudge, so review *quality* is visible without blocking
+anyone. When `hub.review.requireEngagement: true`, only `verified` approvals are counted toward the
+sets above (a determined faker can still run an empty session — the signal is **gameable by design**;
+it raises the cost of a rubber-stamp and makes laziness visible, it does not prove a human read the
+artifact). Philosophy: *visible, not impossible.*
+
 **Touched domains** are resolved from files, not hardcoded:
 - Architecture+contract review: the touched domains are the epic's `repos` (every repo shares the
   contract surface).
@@ -55,6 +64,15 @@ counterpart to the `reviews/*--comments.md` markdown). It does **not** feed the
 alone decide the gate — but it makes the `approved.md` roster's "Reviewed / commented by" section
 attributable, and it is the same shape a future service or the platform bridge can write.
 
+## Non-blocking companion comments (`<!-- yad:noblock -->`)
+The Review Companion posts scaffolding comments (the card deck, the chat log) and the social nudge.
+These are fun/interactive aids, **not** review objections, so they must never hold the PR/MR — yet they
+are deliberately **left unresolved** so they remain in the PR/MR history forever (anyone can scroll back
+to see the trailer, cards, chat, and nudges). Every such comment carries a `<!-- yad:noblock -->`
+marker, and the gate **excludes marked threads** from the unresolved-thread blocking check (so it does
+not "resolve to pass" — it ignores them). A reviewer's *genuine* concern is posted **without** the
+marker and blocks normally, exactly as a `CHANGES_REQUESTED` or any unresolved human thread does.
+
 ## Platform-backed input (the bridge)
 When the hub has a platform (`.sdlc/hub.json`) and the bridge is enabled, reviewers can approve/comment
 on a real PR/MR instead of (or as well as) the skill recording it directly. `action: sync`