yadflow 3.0.0 → 3.1.0

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`