yadflow 3.18.1 → 4.0.0-next.1

package/skills/yad-implement/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: yad-implement
-description: 'Build-half Step B of the gated SDLC. With the dev lens, implement ONE atomic task from a story''s Spec Kit tasks.md as a small diff (≤3 files) on its own branch in the code repo. The diff stays inside the files the task declared — flag and STOP if it would grow beyond them. Commit per convention, ending with the task ID; add Contract-Change: yes only if the diff touches the locked contract surface (which routes back to the architecture gate). The step never advances itself; it produces a committed branch and hands off to the check gates, which the orchestrator (yad-run) may auto-run once `implement` is earned to machine_advance (Phase 4b Step D) — the merge still needs the gates and the engineer review. Use when the user says "implement task <id>" or after a story is spec''d.'
+description: 'Build Step B of the gated SDLC. With the dev lens, implement ONE atomic task from a story''s Spec Kit tasks.md as a small diff (≤3 files) on its own branch in the code repo. The diff stays inside the files the task declared — flag and STOP if it would grow beyond them. Commit per convention, ending with the task ID; add Contract-Change: yes only if the diff touches the locked contract surface (which routes back to the architecture gate). The step never advances itself; it produces a committed branch and hands off to the check gates, which the orchestrator (yad-run) may auto-run once the team sets `implement` to `advance: auto` (`yad dial`) — the merge still needs the gates and the engineer review. Use when the user says "implement task <id>" or after a story is spec''d.'
 ---
 
-# SDLC — Implement Task (build-half Step B)
+# SDLC — Implement Task (Build Step B)
 
 **Goal:** Turn ONE atomic task from a story's `tasks.md` (produced by Step A `yad-spec`) into a small,
 reviewable diff on its own branch in the code repo. **One atomic task = one branch = one PR/MR**
@@ -14,7 +14,7 @@ This step **never auto-advances**. When the task is implemented and committed, c
 **check gates** (Step C — `yad-checks`: spec-link, contract-check, build/test/lint) and then human/AI
 review (Steps D–E, not built yet). Implementation here produces a branch + commit and stops.
 
-The implementing lens is **`dev`** (`bmad-agent-dev`, Amelia). The dev writes only what the task
+The implementing lens is **`dev`**. The dev writes only what the task
 declares; it does not redesign, does not widen the contract, and does not pick up sibling tasks.
 
 ## Conventions
@@ -30,7 +30,7 @@ declares; it does not redesign, does not widen the contract, and does not pick u
   `Co-Authored-By:` for any AI tool that helped author the diff (the human author owns the commit;
   trailer order `Task:` → `Contract-Change:` → `Co-Authored-By:`). The skill installs a `.gitmessage`
   template that scaffolds these (Step 2).
-- Speak in the configured `communication_language`; write code/comments in `document_output_language`.
+- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write code/comments in `document_output_language`.
 
 ## Inputs
 
@@ -55,7 +55,7 @@ rather than forking a second one (one task = one branch).
 **On the first implement in a repo, install the commit template** (idempotent): copy this skill's
 `templates/.gitmessage` to `<repo>/.gitmessage` and run `git -C <repo> config commit.template .gitmessage`
 so every commit is pre-scaffolded with the `Task:` trailer and the commented per-commit `Co-Authored-By:`
-choices (`config.yaml` `build.ai_coauthor.allowed`). Do the same at the hub root for hub commits. Skip if
+choices (`config.yaml` `build.ai_coauthor.allowed`). Do the same at the Product root for Product commit. Skip if
 already configured.
 
 ### Step 3 — Read the spec inputs (do NOT re-derive the contract)
@@ -77,9 +77,14 @@ declared files are wrong is a spec bug, not an implementation decision.
 
 This stop is a **scope overrun** — a halt condition that pulls in a human regardless of any automation
 dial. When this step is driven by the orchestrator (`yad-run`, Phase 4), the stop must be legible to
-it: mark the `implement` step `status: blocked` in `build-state/<story>.json` and surface
-`scope_overrun: true` so the run records a `rejected` trust entry and halts (it never advances past a
-boundary breach). The same applies to the Step 5 contract-surface stop (`contract_touch: true`).
+it: mark the `implement` step `status: blocked` in `build-state/<story>.json` — **with a `record`**,
+`{ "reason": "scope overrun: <which file>", "by": "<login or null>", "date": "<YYYY-MM-DD>" }` — and
+surface `scope_overrun: true` so the run records a `rejected` trust entry and halts (it never advances
+past a boundary breach). The same applies to the Step 5 contract-surface stop (`contract_touch: true`).
+
+The record is what makes the halt legible. Since shape 7 (E38) a `blocked` step carrying nothing
+reads as `todo` — "not started" — because that is what the word meant in every file written before
+shape 7. The record is the only thing that separates a lane that stopped from a lane nobody began.
 
 ### Step 5 — Contract-surface check (local pre-flight for Step C)
 Determine whether the diff touches the **locked contract surface** (the API/event/data-model shapes in
@@ -89,9 +94,18 @@ A contract change means the diff alters the agreed cross-repo shape itself.
 
 - If the diff does **not** change the surface: proceed; no `Contract-Change` trailer.
 - If the task **requires** changing the surface: **flag and STOP**. The contract is owned upstream;
-  route back to the **architecture gate** to amend and re-lock `contract.md` first. Only then return
+  route back to the **architecture gate** to amend and re-lock `contract.md` first — on a route that
+  has one; the short lanes do not, see the bullet below. Only then return
   here, and record `Contract-Change: yes` in the commit body (the Step C contract-check will require a
   matching, already-updated contract).
+- **Short-lane epics have no contract and no architecture gate.** Read
+  `epics/<epic>/.sdlc/state.json`'s `profile` (or, on an epic seeded before file shape 6, what its
+  `steps[]` contains): on `chore` and `spike` there is no `contract.md`, so
+  there is no surface block to compare against and **no gate to route back to**. Never write
+  `Contract-Change: yes` on a short-lane task: there is no lock for the check to verify it against, so
+  the claim cannot be true of anything. Where the Product repo is reachable the gate now FAILS it
+  outright; where it is not, the check defers and nothing catches it. If the task needs the shared cross-repo surface to change, **STOP and escalate
+  to a human**: the work belongs to a new epic on `classic`.
 
 ### Step 6 — Commit on the task branch
 Stage only the declared files. Commit with the convention: a conventional subject, a short body, and a
@@ -103,19 +117,19 @@ never on the AI's own initiative. Keep all trailers in one contiguous block. Do
 ### Step 7 — Report; the advance decision belongs to the dial (Phase 4)
 Report: the branch name, the files changed, how the change satisfies the task's acceptance criterion,
 the result of any test/smoke run, and the next action — the **check gates** (Step C — `yad-checks`)
-then the PR and review (Steps D–E). Do **not** open a PR, merge, or hand-edit the epic's front-half
+then the PR and review (Steps D–E). Do **not** open a PR, merge, or hand-edit the epic's Shape
 `state.json`. Step B ends at a committed task branch.
 
 - **Run standalone:** stop here; a human triggers the gates.
 - **Run by the orchestrator** (`yad-run`): this skill still just produces the committed branch and
   signals success (or a scope/contract halt). The orchestrator records the `implement` step's status
-  and trust entry and, when `implement` is earned to `machine_advance` (Step D, Phase 4b), **auto-runs
+  and trust entry and, when `implement` is set to `advance: auto` (`yad dial`), **auto-runs
   the check gates** instead of waiting for a manual nudge. The diff still cannot merge without the
   gates passing and the engineer review — Step D removes only the "now run the gates" hand-off.
 
 ### Step 8 — Record the `tasks` trust signal on first consume (Phase 4b)
 Resolving a task from `tasks.md` (Step 1) is the moment the generated task list "survives contact" —
-the evidence that could later earn the `tasks` step a `machine_advance`. When driven by `yad-run`,
+part of the run record `yad dial` shows beside the `tasks` dial. When driven by `yad-run`,
 finalize a `tasks` trust entry, anchored to what the human/dev actually did with the list:
 - the task is implemented with its declared `Files:`/scope **as generated** → `approved-unchanged`;
 - the task is **re-scoped** first (its `Files:`/boundary edited) → `approved-with-edits`
@@ -124,8 +138,8 @@ finalize a `tasks` trust entry, anchored to what the human/dev actually did with
 Write the entry to its own shard `epics/<epic>/.sdlc/trust-log/<story>-<repo>-tasks-<uid>.json` (a fresh
 `uid` per run, so concurrent writers never conflict; readers union the folded `trust-log.json` + the
 loose shards, skipping any shard whose full `(story, repo, step, uid)` already appears folded — a
-half-applied `yad tidy up` — so entries are never double-counted). 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,
+half-applied `yad tidy up` — so entries are never double-counted). Schema: `../yad-epic/references/state-schema.md`. The record is advice: the `tasks` dial
+is whatever the team sets with `yad dial`. (The `implement` step's own verdict is finalized later,
 at the engineer review in `yad-engineer-review`: merged as authored → `approved-unchanged`; edited first →
 `approved-with-edits`; scope/contract/checks halt → `rejected`.)
 
@@ -136,7 +150,7 @@ at the engineer review in `yad-engineer-review`: merged as authored → `approve
 - **Never widen the contract here.** Surface changes go back to the architecture gate (Step 5).
 - **The step never advances itself.** A scope overrun or contract touch always halts. The
   `implement → checks` hand-off advances only when the orchestrator's `implement` dial is
-  `machine_advance` (earned, Step D) — and never past the engineer review, which is always human.
+  `advance: auto` (`yad dial`) — and never past the engineer review, which is always human.
   Standalone, the step stops at a committed branch.
 
 ## Reference

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

@@ -89,8 +89,8 @@ The **locked contract surface** is the cross-repo agreement in `epics/<epic>/con
   change; no trailer.
 - **Changing the contract** (exceptional) — altering the agreed shape itself (new field crossing repos,
   changed status enum, new shared endpoint). This is **not** an implementation decision. Stop, go back
-  to the **architecture gate**, amend and re-lock `contract.md` (which re-escalates that review per the
-  contract `risk_tags`), and only then implement — recording `Contract-Change: yes` so the §C
+  to the **architecture gate**, amend and re-lock `contract.md` (which sends that review round again; its contract `risk_tags`
+  raise the full approver count, which is advisory — E72 reports it capped at the active people less one), and only then implement — recording `Contract-Change: yes` so the §C
   contract-check finds the matching, already-updated contract.
 
 This keeps the contract singular and owned upstream: a code repo can never widen the shared surface

package/skills/yad-learn/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-learn
-description: 'The cross-cutting learning layer: at ANY SDLC stage, a team member can ask to learn a concept and be tutored in the context of what the team is building. Routes the request to the connected learning tool (.sdlc/learning.json, DeepTutor-first) grounded in the project knowledge base, or degrades to harness-native tutoring (the harness model reading the artifacts) when no tool is connected. Renders a tutorial artifact and appends to a per-member learning ledger that is kept LOCAL-ONLY — gitignored, never committed or pushed to the product hub or any code repo — so it stays a private, personal skills log (yad-status rolls up the local records). Purely opt-in — it NEVER blocks a gate and never touches epic state, approvals, or the contract lock. Use when the user says "teach me <concept>", "learn about <concept>", or "yad-learn".'
+description: 'The cross-cutting learning layer: at ANY SDLC stage, a team member can ask to learn a concept and be tutored in the context of what the team is building. Routes the request to the connected learning tool (.sdlc/learning.json, DeepTutor-first) grounded in the project knowledge base, or degrades to harness-native tutoring (the harness model reading the artifacts) when no tool is connected. Renders a tutorial artifact and appends to a per-member learning ledger that is kept LOCAL-ONLY — gitignored, never committed or pushed to the Product or any code repo — so it stays a private, personal skills log (yad-status rolls up the local records). Purely opt-in — it NEVER blocks a gate and never touches epic state, approvals, or the contract lock. Use when the user says "teach me <concept>", "learn about <concept>", or "yad-learn".'
 ---
 
 # SDLC — Learn (the cross-cutting tutor)
@@ -13,8 +13,8 @@ therefore their **control over what is being built** — explicit, without ever
 to the team.
 
 **Learning output is LOCAL-ONLY.** The records ledger and the rendered tutorials are personal artifacts:
-they are **gitignored and must never be committed or pushed** — not to the product hub and not to any
-code repo. The skill ensures the product hub's `.gitignore` lists these paths before it writes them. The
+they are **gitignored and must never be committed or pushed** — not to the Product and not to any
+code repo. The skill ensures the Product's `.gitignore` lists these paths before it writes them. The
 only committed, shared learning file is the connection registry `.sdlc/learning.json` (no secrets, no
 personal data) — written by `yad-connect-learning`, not here.
 
@@ -24,7 +24,7 @@ approvals ledger, or the contract lock. It writes only the local learning ledger
 
 ## Conventions
 
-- `{project-root}` resolves from the project working directory (the **product hub**).
+- `{project-root}` resolves from the project working directory (the **Product**).
 - The tutor is reached via the project's learning connection (`.sdlc/learning.json`, written by
   `yad-connect-learning`). **DeepTutor-first** (a CLI subprocess); when no tool is connected (or the
   `deeptutor` binary is absent) it degrades to **harness-native** tutoring — the harness model reads the
@@ -35,7 +35,7 @@ approvals ledger, or the contract lock. It writes only the local learning ledger
 - When no epic is scoped, records go to `.sdlc/learning-records.json` and tutorials to `.sdlc/learning/`
   (cross-project learning).
 - **Local-only, never committed.** All of the above paths are personal output. Before writing any of
-  them, ensure the **product hub's** `.gitignore` ignores learning output (idempotent — append only if
+  them, ensure the **Product's** `.gitignore` ignores learning output (idempotent — append only if
   the lines are absent):
   ```
   # yadflow learning layer — personal, local-only (never commit or push)
@@ -44,10 +44,10 @@ approvals ledger, or the contract lock. It writes only the local learning ledger
   epics/*/.sdlc/learning-records.json
   epics/*/learning/
   ```
-  Never write learning output into a connected **code repo** — it lives only in the product hub, and only
+  Never write learning output into a connected **code repo** — it lives only in the Product, and only
   on the local machine. `.sdlc/learning.json` (the connection registry) is the sole committed learning
   file and is NOT ignored.
-- Speak in the configured `communication_language`; write tutorials in `document_output_language`.
+- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write tutorials in `document_output_language`.
 
 ## Inputs
 
@@ -84,7 +84,7 @@ Keep the tutorial focused (usually < 600 words): explain the concept, then tie i
 example from this project** (an artifact line, a contract field, a story).
 
 ### Step 2 — Render the tutorial artifact (local-only)
-First ensure the product hub's `.gitignore` lists the learning-output paths (see Conventions — append the
+First ensure the Product's `.gitignore` lists the learning-output paths (see Conventions — append the
 block only if absent, so the artifacts can never be committed or pushed). Then write the tutorial to
 `epics/EP-<slug>/learning/<member>--<concept-slug>.md` (or `.sdlc/learning/` when no epic is scoped).
 Front-matter the file with `member`, `concept`, `stage`, `tool`, and `requestedAt`.
@@ -130,7 +130,7 @@ there is no approval and no gate. The learner runs `action: complete` (below) wh
 - **Read-only except the learning ledger.** It writes only `learning-records.json` + tutorial artifacts;
   it never touches `state.json`, `approvals.json`, `comments.json`, or the contract lock.
 - **Local-only output.** The records ledger and tutorials are gitignored personal artifacts — never
-  commit or push them, and never write them into a code repo. Ensure the hub `.gitignore` covers them
+  commit or push them, and never write them into a code repo. Ensure the Product `.gitignore` covers them
   before writing (see Conventions).
 - **Always works.** No DeepTutor / no connection → tutor harness-native. Never fail because a tool is
   absent.

package/skills/yad-learn/references/learning-state.md

@@ -12,7 +12,7 @@ evidence base for the **local skills-log roll-up** in `yad-status`.
 (`config.yaml` `learning.records` and `learning.artifacts`.)
 
 **Local-only.** Every path above is personal output and is **gitignored — never committed or pushed**, to
-the product hub or any code repo. `yad-learn` ensures the hub `.gitignore` lists them before writing. The
+the Product or any code repo. `yad-learn` ensures the Product `.gitignore` lists them before writing. The
 only committed learning file is the connection registry `.sdlc/learning.json`.
 
 ## Record schema
@@ -42,7 +42,7 @@ only committed learning file is the connection registry `.sdlc/learning.json`.
 - **No secrets.** Records hold concept text + references only — never keys or raw tool output beyond the
   rendered tutorial.
 - **Never commit the ledger or tutorials.** They are personal, local-only artifacts: gitignored, never
-  committed or pushed (to the hub or a code repo). Only `.sdlc/learning.json` is committed.
+  committed or pushed (to the Product or a code repo). Only `.sdlc/learning.json` is committed.
 
 ## Mode → DeepTutor capability
 

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

@@ -1,15 +1,15 @@
 ---
 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".'
+description: 'Build 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. Assigns the PR/MR to the logged-in gh/glab login and requests no reviewers (ask them on the PR itself); prints a reviewer suggestion from recent history and CODEOWNERS, a hint and never a request. High risk / contract surface raises the approver count (risk-route.sh prints it). 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)
+# SDLC — Open Task PR/MR (Build 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.
+(installed by `yad-pr-template`, Step D), with the body prefilled and the assignee set.
 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.
+Step E) owns the merge. Distinct from `yad gate open`, which opens a Shape artifact-review PR on
+the Product.
 
 ## Conventions
 
@@ -19,19 +19,20 @@ the product hub.
 - **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`
+  `.gitlab/merge_request_templates/Default.md`) with the Summary (from the commit), the story/task id and
+  its `specs/` path, `Risk level:`, `Contract surface touched:`, and `Domains` (the repo name when
+  `--repo` is passed) prefilled; the rest is left for the author. This satisfies the `pr-template`
   gate.
-- **Stage-aware on the product hub** — `open-pr` mirrors the `--head` split the hub gates apply:
-  - a **`review/EP-*/<artifact>`** branch is a front-half artifact-review PR → it **delegates to
-    `yad gate open`** (artifact-review title `review: <artifact> (EP-<slug>)`, the hub artifact-review
+- **Stage-aware on the Product** — `open-pr` mirrors the `--head` split the Product gates apply:
+  - a **`review/EP-*/<artifact>`** branch is a Shape artifact-review PR → it **delegates to
+    `yad gate open`** (artifact-review title `review: <artifact> (EP-<slug>)`, the Product artifact-review
     body, and the gate ledger bookkeeping all in one place). Any `--title`/`-m` is ignored here.
-  - any **other hub branch** is a tooling/CI change → it uses the bundled **code-task** template
-    (`## Summary` / `Risk level:` / `## Checklist`) instead of the hub's artifact-review
-    `pull_request_template.md`, so the hub `pr-template` gate passes.
+  - any **other Product branch** is a tooling/CI change → it uses the bundled **code-task** template
+    (`## Summary` / `Risk level:` / `## Checklist`) instead of the Product's artifact-review
+    `pull_request_template.md`, so the Product `pr-template` gate passes.
   In a code repo nothing changes — it reads the repo's own committed code-task template.
 - **Base branch** — **resolved, never assumed.** In order: `--base` → the repo's `default_branch` in
-  `.sdlc/repos.json` → (for a PR against the hub itself) `hub.json`'s `default_branch` → what the
+  `.sdlc/repos.json` → (for a PR against the Product itself) `hub.json`'s `default_branch` → what the
   platform reports (`gh repo view --json defaultBranchRef` / `glab api projects/:id`) → local
   `origin/HEAD` → `main`. The same **configuration-outranks-the-remote** order `yad repo sync` and the
   contract-check gate already use (they stop at `origin/HEAD`; only this chain also asks the platform).
@@ -41,18 +42,28 @@ the product hub.
   auto-review eligibility from the base at PR-**open** time, and retargeting afterwards does not undo
   the skip. Hardcoding `main` here is the same bug the check gates already refuse to make (see
   `../yad-checks/references/check-gates.md`).
-- **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.
+- **Assignee** — the person opening it: `@me` on GitHub (`gh` resolves it on the repo's own host), and
+  on GitLab the login `glab` reports (no assignee is passed when that lookup fails). **No reviewers are
+  requested** (E62): yadflow keeps no list of people. The CLI prints `no
+  reviewers were requested — ask them on the PR itself`. For a `high` directory the CLI names the people
+  who have worked there lately (E67, Step 3). For every code-repo change it also prints a reviewer **suggestion**
+  (E68, Step 3a): who has committed in the touched folders lately, and what CODEOWNERS lists — a hint
+  only, never a request.
+- **Routing** — the merge needs 1 approval from someone other than the author (the base). `high` risk
+  adds 1, a touched contract surface adds 2, and a change touching a `high` directory on the base
+  branch's risk map adds 1 (E66) — the larger, never the sum. That risk step is advisory: branch
+  protection holds the merge, never this count. The CLI prints the count once the PR is open — capped by
+  the active people (E72) when run from the Product — for example `this PR asks for 3 approvers = base 1
+  + contract risk 2, capped to 1 for 2 active people — base enforced, risk step advisory; …` — and prints the count of people on its
+  own line (`active people: not counted — no cap applies; …` when it cannot count them).
+  `bash checks/risk-route.sh <body>` prints the same count from the PR body, without the cap: a code
+  repo's CI has no Product to count people from.
 
 ## 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.
+- `contractChange` — flag; marks the contract surface touched and raises the approver count.
 - `base`           — override the PR/MR base (optional; defaults to the repo's own default branch —
   see **Base branch** above). Only pass it deliberately: a non-default base loses the AI first pass.
 - `platform` / `title` — optional overrides.
@@ -69,8 +80,8 @@ 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. It prints the base it resolved and where that came
-from.
+PR/MR with the assignee set and no reviewers requested. It prints the base it resolved and where that
+came from.
 
 The non-default-base warning is **advisory — it does not block, and the PR/MR is already open by the
 time you read it.** If the base was intended (a stacked PR, a release branch), carry on. If it was
@@ -78,9 +89,33 @@ not, do **not** just retarget the open PR — that leaves the AI first pass skip
 cause (the repo's `default_branch`, or drop the wrong `--base`), and re-run `yad open-pr` so the PR
 is *created* against the right base.
 
-### 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 3 — Route the review (if the count is raised)
+Once the PR is open, the CLI prints how many approvers it asks for — the same count the engineer review
+(`yad-engineer-review`) uses. It joins the body's level (`--risk`, `--contract-change`) with the code
+repo's risk map on `origin/<base>`: a change touching a `high` directory adds 1 even when the body says
+`low`, and the CLI warns that the two disagree. It also names who has **committed in those directories
+in the last 30 days** (E67) — the people who can meet that ask — or says plainly that nobody has, or
+that the history could not be read. It only prints; the body keeps the author's level. If
+the level in the body is wrong, fix the body on the PR. When the map cannot be read (no `origin/<base>`
+fetched, a newer map), it says so and counts the body alone. `bash checks/risk-route.sh "<pr body>"`
+also lists the touched domains as a hint for whom to ask; request those reviewers on the PR/MR yourself.
+
+### Step 3a — Relay the reviewer suggestion (E68)
+The CLI then prints two hints about whom to ask, on separate lines: the people who have **committed in
+the folders this change touches in the last 30 days** (base branch; the change's own authors and robots
+left out; ranked by commits, five shown), and what **CODEOWNERS on the base branch** lists for the changed
+files. Relay both as they are. It is a **suggestion only**:
+
+- Never request those people as reviewers on the PR/MR yourself, and never call them owners or required
+  approvers. A name is a hint about who **may** know the code. The author decides whom to ask.
+- CODEOWNERS is a hint: these files go stale. A `CODEOWNERS line N not read — …` line is a line yadflow
+  could not match safely (the first three get a reason, the rest a count, and the list then says it
+  `may be wrong`); mention it, do not guess what it meant.
+  If the author asks whether CODEOWNERS is out of date, run `yad codeowners check <repo>` (E69) and relay
+  it. Never edit CODEOWNERS for them: a name written there becomes an owner the platform can enforce.
+- The same person can appear in both lists under two names (a git name, a platform login). Do not join
+  them unless the output says `also in the 30-day history` (only a `noreply` login of the same platform counts, and only on github.com or gitlab.com).
+- `not read` (a shallow clone, a missing base) is never "nobody". Say it as the CLI says it.
 
 ### 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
@@ -93,8 +128,8 @@ The full fun-review flow (cards + grounded chat + engagement) is driven by the
 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).
+Report the PR/MR URL and that no reviewers were requested. The PR now runs the check gates (Step C);
+the human engineer review and merge happen in `yad-engineer-review` (Step E).
 
 ## Hard rules
 
@@ -102,7 +137,7 @@ engineer review and merge happen in `yad-engineer-review` (Step E).
 - **The base is the repo's default branch** unless you deliberately chose otherwise with `--base`.
   Never hardcode `main`, and never ignore the non-default-base warning silently.
 - **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.
+- **High risk raises the approver count** — the same count as the gate; never a separate rule.
 - **Opening a PR never merges.** The human owns the merge in Step E.
 
 ## Reference

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

@@ -1,6 +1,6 @@
 ---
 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".'
+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 Build code PR/MR (yad review) and the Shape 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)
@@ -26,19 +26,19 @@ platform.**
 
 ## 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]`.
+- `{project-root}` resolves from the project working directory — the **Product**.
+- Build (code PR/MR): grounded by `yad review walkthrough --repo <r> --pr <n>`.
+- Shape (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
+- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write any rendered tutorial in
   `document_output_language`.
 
 ## Inputs
 
-- Back half: `repo` + `pr`. Front half: `epic` + `artifact`.
+- Build: `repo` + `pr`. Shape: `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).
@@ -47,9 +47,11 @@ platform.**
 
 ### 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
+- Build: `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.
+- Shape: `yad gate walkthrough <epic> [artifact]` → the same, over the artifact's review diff. Its
+  `step.gateRule` carries the step's full approver count (`needed` distinct people, and the `risk`
+  tier that set it), and `step.cap` — an object `{ active, limit, to, capped }`: `to` is the count capped by the active people (E72), `capped` is true when the cap lowered it, and the whole field is `null` when the people were not counted — useful context for how hard a step is being reviewed, never a pass/fail input.
 
 **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
@@ -87,8 +89,8 @@ After the last stop:
   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
+  `engagement: verified` — Build: `gh pr review <n> --approve --body "<note>\n\n<!-- yad:engagement verified -->"`
+  (GitLab: `glab mr approve <n>` then a note with the marker); Shape: 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
@@ -101,11 +103,11 @@ addresses them) — nothing advances on a half-finished session.
    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` =
+   `review <repo> PR #<n> — <title>` (Shape: `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 —
+   **First ensure the Product `.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".
 
@@ -125,9 +127,9 @@ addresses them) — nothing advances on a half-finished session.
   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)
+## local mode (no platform)
 
-With no hub platform there is no PR to post to: write the session record to
+With no Product 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
@@ -138,7 +140,7 @@ the posting surface differs.
 - 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 Build merge gate it enriches: [`yad-engineer-review`](../yad-engineer-review/SKILL.md).
+- The Shape 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/session-state.md

@@ -22,7 +22,7 @@ Sections (you generate the prose; the helper composes them):
 - **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.
+local mode write it to `reviews/<base>--<date>--pair-session.md` instead.
 
 ## 2. The learning record (local-only, reuses yad-learn)
 
@@ -30,7 +30,7 @@ This is the "review **is** the lesson" half. It reuses [`yad-learn`](../../yad-l
 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
+**Before writing anything**, ensure the **Product's** `.gitignore` covers the learning paths
 (idempotent — append only if absent), the same block yad-learn uses:
 
 ```
@@ -62,7 +62,7 @@ cross-project), using yad-learn's exact field shape:
 ```
 
 Field notes:
-- `stage` = `engineer-review` (back half) or `<artifact>-review` (front half, e.g. `architecture-review`).
+- `stage` = `engineer-review` (Build) or `<artifact>-review` (Shape, 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).
@@ -74,7 +74,7 @@ engineer's specific gaps and how to close them. Both files are **local-only, git
 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)
+## Optional: stamp the build-log (Build)
 
 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,