yadflow 3.18.1 → 4.0.0-next.1

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

@@ -3,18 +3,18 @@
 `yad-docs-overview` reuses the per-epic shell, but the *content* is the **workflow itself** rather than
 one epic's flows. This file pins how the setup→ship pipeline maps onto the shell's primitives. The
 ordering source of truth is `skills/sdlc/module-help.csv` (`phase`, `preceded-by`, `followed-by`,
-`outputs`); the dials/thresholds come from `skills/sdlc/config.yaml`; the node classes come from
+`outputs`); the dial defaults come from `skills/sdlc/config.yaml`; the node classes come from
 `docs/diagrams/sdlc-overview.mmd`.
 
 ## Primitive mapping
 
 | Shell primitive | Overview meaning |
 |-----------------|------------------|
-| `FlowPath` (`paths.ts`) | a **phase**: Setup, Front-zero (discovery), Front half, Build half, Automation, Change management (feature threads). |
+| `FlowPath` (`paths.ts`) | a **phase**: Setup, Front-zero (discovery), Shape, Build, Automation, Change management (feature threads). |
 | `FlowStep` (within a path) | a **skill or gate** in order; `messages` = its `outputs`; `sideEffects` = the `.sdlc/` files it writes; `status`/`bookingStatus` annotate gated vs. enrichment vs. earned. |
-| `SystemComponent` (`components.ts`) | a **durable state object** (the hub, each `.sdlc/*.json`, code repos, the design/testing/learning tools, the platform). |
+| `SystemComponent` (`components.ts`) | a **durable state object** (the Product, each `.sdlc/*.json`, code repos, the design/testing/learning tools, the platform). |
 | `RoleConfig` (`roles.ts`) | a **lens** → its relevant sections + paths. |
-| doc sections (`docSections.ts`/`referenceData.ts`) | the phase narratives + the dial/threshold reference tables (from `config.yaml` + the build-plan docs). |
+| doc sections (`docSections.ts`/`referenceData.ts`) | the phase narratives + the dial reference tables (from `config.yaml` + the build-plan docs). |
 
 ## Flow paths = phases, with their skills in order
 
@@ -26,40 +26,59 @@ and never gates.
 
 | Step (skill) | Outputs / sideEffects |
 |--------------|------------------------|
-| `yad-connect-repos` | `repos.json`, `code-context/<repo>/pack.md` + `code-map.md` (+ `detect-hub`/`roster` → `hub.json`) |
+| `yad-connect-repos` | `repos.json`, `code-context/<repo>/pack.md` + `code-map.md` (+ `detect-hub` → `hub.json`) |
 | `yad-connect-design` | `design.json` |
 | `yad-connect-testing` | `testing.json` |
 | `yad-connect-learning` | `learning.json` |
 | `yad-connect-docs` | `docs.json` |
 
 ### Path: Front-zero (`phase: 0-front`)
-The OPTIONAL once-per-project discovery phase, modelled as the reserved "epic zero" `EP-discovery`.
-Greenfield AND brownfield; a 2-step author→review chain whose review binds to the whole artifact set
-and terminates at `discovery-done` (no build half).
+The OPTIONAL once-per-product **Foundation** (E75) — the Product level, in its own folder `foundation/`
+under the fixed id `EP-foundation`. Greenfield AND brownfield; a 2-step author→review chain whose
+review binds to the required sections and terminates at `foundation-done` (no Build). Its approval is
+reported, not enforced, before feature work begins.
 
 | Step (skill) | Gate | Outputs / sideEffects |
 |--------------|------|------------------------|
-| `yad-discovery` *(optional)* | → `discovery-review` (base rule) | `market-research.md`, `competitor-analysis.md`, `current-state.md`, `feasibility.md`, `requirements.md`, `roadmap.md`; seeds `EP-discovery/.sdlc/state.json` |
+| `yad foundation new` then `yad-discovery` *(optional)* | → `foundation-review` (base rule) | `purpose.md`, `scope.md`, `mvp.md`, `roadmap.md`, `stack.md`, `repos.md` (+ optional `market.md`, `risks.md`); seeds `foundation/.sdlc/state.json` |
 
 `roadmap.md` is the menu of features each `yad-epic` reads (Step 2c) — reference-only, never
-auto-seeds epics.
-
-### Path: Front half (`phase: 1-front`)
+auto-seeds epics. A product created before E75 may still hold the old spelling, `epics/EP-discovery/`
+(six files, ending at `discovery-done`); `yad migrate --apply` converts it on a local ledger.
+
+<!-- `1-front` and `3-build` are DATA — the `phase` column in skills/sdlc/module-help.csv, which
+     the overview build reads. The Shape/Build/Run rename deliberately left them alone: change-safety
+     rule 3 says a release may add but never rename, so a stored value moves in a major with a
+     migration, not in a wording sweep. The display names below are the new vocabulary; the ids are
+     the old one, on purpose. -->
+
+<!-- Each skill's `phase` in module-help.csv agrees with where this model places it. `4-automate` holds
+     yad-run and the docs skills; `6-change` holds yad-change, yad-stub, yad-timeline, yad-defects and
+     yad-reconcile; yad-status (a read-only view) and yad-learn (a tutor for any stage) are `anytime`, the
+     value for a skill available at every stage — they are listed under
+     Automation below only because the site needs one place to draw them. yad-report has no phase: it is
+     a CLI helper, not a pipeline step.
+     Moving three of these from `1-front` needed no migration, and that does not contradict the note
+     above: module-help.csv is catalogue content the tool ships, read from the package's skills/sdlc/ folder
+     and never installed into a project. It is not state a user's project stores. The note above is about
+     the `1-front` / `3-build` ids as they are read back. -->
+
+### Path: Shape (`phase: 1-front`)
 The gated authoring chain + the reusable review gate (10 steps, or 12 with the optional analysis).
 
 | Step (skill) | Gate | Outputs / sideEffects |
 |--------------|------|------------------------|
 | `yad-analysis` *(optional)* | → `analysis-review` | `analysis.md`, seeds `state.json` |
 | `yad-epic` | → `epic-review` | `epic.md`, seeds `state.json` |
-| `yad-architecture` | → `architecture-review` (escalates on contract) | `architecture.md`, `contract.md`, `contract-lock.json` |
+| `yad-architecture` | → `architecture-review` (contract tag raises the count) | `architecture.md`, `contract.md`, `contract-lock.json` |
 | `yad-ui` | → `ui-design-review` | `ui-design.md`, `DESIGN.md`, `design-links.json` |
-| `yad-stories` | → `stories-review` (per-repo routing) | `stories/EP-<slug>-S0N.md` |
+| `yad-stories` | → `stories-review` (labelled with every touched repo) | `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`)
+### Path: Build (`phase: 3-build`)
 Per-story, per-repo: `spec → tasks → implement → checks → engineer-review`, plus the commit/PR helpers.
 
 | Step (skill) | Outputs / sideEffects |
@@ -70,15 +89,15 @@ Per-story, per-repo: `spec → tasks → implement → checks → engineer-revie
 | `yad-pr-template` | PR/MR template + routing helpers |
 | `yad-commit` / `yad-open-pr` / `yad-ship` | one commit / one PR/MR |
 | `yad-engineer-review` | engineer review + ship recorded as a `build-log/` shard |
-| `yad-backfill` | DRAFT specs for legacy features |
+| `yad-backfill` | DRAFT specs for legacy features — its own step in the Build path (Step G, brownfield) |
 
-### Path: Automation (the second dial + observation)
+### Path: Automation (`phase: 4-automate`) — the second dial + observation
 The orchestrator + the trust evidence + the read-only views. Maps the **earns** / **locked** / **sentinel**
 node classes from the diagram.
 
 | Step (skill) | Outputs / sideEffects |
 |--------------|------------------------|
-| `yad-run` | drives the back-half loop; `build-state/<story>.json`, `trust-log.json`, kill switch |
+| `yad-run` | drives the Build loop; `build-state/<story>.json`, `trust-log.json`; dials and kill switch through `yad dial` / `yad kill` (`.sdlc/automation.json`) |
 | `yad-learn` | tutoring; `learning-records.json` (LOCAL-ONLY, gitignored) |
 | `yad-status` | read-only view (no writes) |
 | `yad-docs` / `yad-docs-overview` / `yad-docs-sync` | the docs sites + their `docs-build.json` manifests |
@@ -86,24 +105,24 @@ node classes from the diagram.
 ### Path: Change management — feature threads (`phase: 6-change`)
 The post-lock evolution layer. Once an epic is **sealed** (all stories shipped), behaviour can no longer
 be mutated in place — a change request becomes a **new epic threaded to its parent** (genesis → change →
-defect), inheriting unchanged front artifacts **by reference** and re-authoring only what changes, so
+defect), inheriting unchanged Shape artifacts **by reference** and re-authoring only what changes, so
 locked artifacts are never mutated and never go stale, only superseded. Three CI gates enforce the thread
-(`lineage-check`, `epic-open`, `reconcile-debt`). This path never gates the front chain; `yad-change` is
+(`lineage-check`, `epic-open`, `reconcile-debt`). This path never gates the Shape chain; `yad-change` is
 the intake, then it hands off to the normal authoring skills + the review gate.
 
 | Step (skill) | Outputs / sideEffects |
 |--------------|------------------------|
-| `yad-change` | intake + triage depth (defect-fix / behavioral-no-surface / contract-surface / new-capability); seeds a threaded change-epic — lineage frontmatter, inherited-step `state.json`, pointer-lock `contract-lock.json`, `change.json`, and `reconcile-debt.json` for hotfixes |
+| `yad-change` | intake + triage depth (defect-fix / behavioral-no-surface / contract-surface / new-capability); writes a threaded change-epic's lineage frontmatter and `change.json`, seeds its ledger with `yad epic new --parent` (inherited-step `state.json`, pointer-lock `contract-lock.json` — E42), and opens `reconcile-debt.json` for hotfixes |
 | `yad-timeline` | `TIMELINE.md` (the thread evolution view) + `thread-resolved.md` (the resolved current truth) |
 | `yad-defects` | `DEFECTS.md` (quality-gap report by `escape_stage` + root cause) |
 | `yad-reconcile` | advisory drift / orphan / debt sweep (read-only; mirrors `yad-docs-sync`) |
 
 CLI: `yad thread [<epic>]` prints a thread + its resolved current truth + open debt; `yad reconcile`
-runs the sweep. The three thread gates ride in the build-half `yad-checks` set above.
+runs the sweep. The three thread gates ride in the Build `yad-checks` set above.
 
 ## System components = the durable state objects
 
-`components.ts` renders these on the canvas (deterministic positions): the **product hub**; each
+`components.ts` renders these on the canvas (deterministic positions): the **Product**; each
 `.sdlc/*.json` (`state.json`, `approvals.json`, `comments.json`, `hub.json`, `repos.json`, `design.json`,
 `testing.json`, `learning.json`, `docs.json`, `contract-lock.json`, `build-state/*`, `trust-log.json`,
 and the change-thread ledgers `change.json`, `reconcile-debt.json`, `build-log.json`);
@@ -121,13 +140,13 @@ The eight yadflow lenses, each to its relevant phase sections + paths:
 
 | Lens | Relevant phases / sections |
 |------|----------------------------|
-| analyst | Setup intent, project discovery (front-zero), analysis step, front-half discovery |
-| pm | project discovery (market/feasibility/roadmap), epic, stories; the front gates |
-| architect | architecture + the locked contract; escalation |
+| analyst | Setup intent, the Foundation (the Product level), analysis step, Shape discovery |
+| pm | the Foundation (purpose/scope/MVP/roadmap), epic, stories; the Shape gates |
+| architect | architecture + the locked contract; the contract risk step |
 | ux | UI design, design tool connection, the design system |
-| dev | build half: spec → implement, the per-repo loop |
+| dev | Build: spec → implement, the per-repo loop |
 | tester | test-cases (parallel track), the testing tool, checks |
-| reviewer | the review gate, comments, the hub bridge |
+| reviewer | the review gate, comments, the Product bridge |
 | engineer | engineer review + ship, the merge gate, automation dial/trust |
 
 ## Determinism + theme

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

@@ -16,14 +16,14 @@ silent (the same discipline as `yad repo refresh`).
 
 ## Conventions
 
-- `{project-root}` resolves from the project working directory (the **product hub**).
+- `{project-root}` resolves from the project working directory (the **Product**).
 - Per-epic baseline: `epics/EP-<slug>/.sdlc/docs-build.json` (written by `yad-docs`). Overview baseline:
   `docs/sdlc-site/.docs-build.json` (written by `yad-docs-overview`).
 - The hashing + build + deploy is the **`yad docs sync` CLI**'s job; the regeneration of a stale site is
   delegated back to `yad-docs` / `yad-docs-overview` (the AI generation step). This skill orchestrates
   the reconcile.
 - The docs target is `.sdlc/docs.json` (`yad-connect-docs`).
-- Speak in the configured `communication_language`; write documents in `document_output_language`.
+- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.
 
 ## Inputs
 
@@ -50,17 +50,22 @@ Read each `docs-build.json` and compare. A site is **stale** when **any** of:
 - any `repoHeads[<repo>]` differs from the repo's current HEAD (the code the components cite advanced —
   the same head-sha staleness as `repos.json`), or
 - for the overview, `config.yaml` / `module-help.csv` / the `.mmd` / `skillCount` moved, or
-- its `templateVersion` < the current shell template version (the shell was upgraded).
+- for a per-epic site, its `shellVersion` differs from the `version` in `skills/yad-docs/templates/app/package.json`
+  (the shell was upgraded). The overview has no shell version: it is updated in place, not re-copied. An
+  older manifest records only `templateVersion` (the yad CLI version, which changed on every release). That
+  value is never compared; such a manifest counts as built on shell `0.0.0`, the only version before this.
 
 A missing `docs-build.json` (a site never generated) counts as **stale → needs generate**.
 
 ### Step 3 — Act on `action`
 - **`check`** (default, **read-only**) — print which sites are stale and **WHY**, in `yad check` drift
   style: *which artifact moved* (name it), *which repo HEAD advanced* (`<repo>: <old>→<new>`), *config /
-  manifest / diagram / skill-count changed*, or *shell upgraded* (`templateVersion`). Writes nothing.
+  manifest / diagram / skill-count changed*, or *shell upgraded* (`shellVersion`, per-epic only). Writes nothing.
 - **`refresh`** — for each stale site, re-run the generator (`yad-docs` for an epic site, `yad-docs-overview`
   for the overview) to regenerate `src/data/*.ts` + theme + manifest, then redeploy via `yad docs deploy`
-  (degrading to build-only when no platform CLI). Report every site refreshed. **Never silent** — refresh
+  (degrading to build-only when no platform CLI). Report every site refreshed, and every site whose
+  rebuild failed: `yad docs sync --refresh` exits 1 when a stale site's npm install or build fails, and
+  its `--json` `sites` rows say which (`built: false` with an `error`). **Never silent** — refresh
   is a deliberate human/CI act, surfaced exactly like `yad repo refresh`.
 - **`wire`** — commit the CI workflow (Step 4) that automates the check + rebuild.
 

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

@@ -16,7 +16,7 @@ the current inputs, or its shell template is out of date. This mirrors the `repo
   "artifactHash": "<sha256 of epic.md + architecture.md + contract.md CONTRACT-SURFACE + ui-design.md + each story>",
   "repoHeads": { "<repo>": "<HEAD sha>" },
   "deployUrl": "<url or null>",
-  "templateVersion": "<shell template version>"
+  "shellVersion": "<the `version` in templates/app/package.json>"
 }
 ```
 
@@ -28,8 +28,7 @@ the current inputs, or its shell template is out of date. This mirrors the `repo
   "theme": "yadflow-brand",
   "artifactHash": "<sha256 of config.yaml + module-help.csv + docs/diagrams/sdlc-overview.mmd>",
   "skillCount": <number of yad-* skills>,
-  "deployUrl": "<url or null>",
-  "templateVersion": "<shell template version>"
+  "deployUrl": "<url or null>"
 }
 ```
 
@@ -55,10 +54,12 @@ A site is **stale** when ANY holds:
    repo is *flagged*, never auto-refreshed: the `code-context` itself is refreshed by a human via
    `yad repo refresh`, and the docs are regenerated only on an explicit `refresh`/CI decision;
 3. (overview) `config.yaml` / `module-help.csv` / the `.mmd` moved — the pipeline changed (this is what
-   enforces "the overview regenerates whenever the workflow definition or skill set changes"); or the
-   `templateVersion` (the yad CLI version) advanced — the doc shell upgraded;
-4. manifest `templateVersion` < the current shell template version — the `templates/app/` shell was
-   upgraded, so every site should re-copy it;
+   enforces "the overview regenerates whenever the workflow definition or skill set changes");
+4. (per-epic) manifest `shellVersion` ≠ the `version` in `templates/app/package.json` — the shell was
+   upgraded, so the site should re-copy it. The overview has no shell version (it is updated in place).
+   A manifest's older `templateVersion` field held the yad CLI version, which moved on every release, so
+   it is never compared: a manifest with only that field counts as built on shell `0.0.0`, the one version
+   the shell had before `shellVersion` existed. It reads fresh today, and a real shell upgrade still shows;
 5. the `docs-build.json` is **missing** — the site was never generated (treat as stale → generate).
 
 `check` reports which of these tripped and why; `refresh` regenerates + redeploys; neither blocks any

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

@@ -1,38 +1,41 @@
 ---
 name: yad-engineer-review
-description: 'Build-half Step E of the gated SDLC — AI review, engineer review, then merge. Wire an advisory AI first-pass (CodeRabbit) on the PR/MR; record the human engineer review with the same human_approve discipline as the front gates (owner + 1 reviewer, escalating to domain owners on high risk / contract / auth / payments — the Step D routing); and on merge, record the ship in the epic build-log and update the story state so the epic → story → task → PR chain is traceable. Never auto-advances — the human owns the merge. Use when the user says "record the engineer review", "merge this task", or "wire the AI review". (To commit + open the PR/MR, use yad-ship.)'
+description: 'Build Step E of the gated SDLC — AI review, engineer review, then merge. Wire an advisory AI first-pass (CodeRabbit) on the PR/MR; record the human engineer review with the same advance-human discipline as the Shape gates (1 distinct approver, who should not be the author; high risk / contract raise the full count, advisory, not enforced — the Step D routing); and on merge, record the ship in the epic build-log and update the story state so the epic → story → task → PR chain is traceable. Never auto-advances — the human owns the merge. Use when the user says "record the engineer review", "merge this task", or "wire the AI review". (To commit + open the PR/MR, use yad-ship.)'
 ---
 
-# SDLC — Engineer Review & Merge (build-half Step E)
+# SDLC — Engineer Review & Merge (Build Step E)
 
 **Goal:** Take a task PR/MR that has passed the **check gates** (Step C) through two sets of eyes and
 out to production: an **AI first-pass** (advisory) and a **human engineer review** (the authority),
-then **ship** — merge, record the ship, and update the story state. This is the last build-half step
-(build plan §E). It is a **human gate**, the same `human_approve` discipline as the front states:
+then **ship** — merge, record the ship, and update the story state. This is the last Build step
+(build plan §E). It is a **human gate**, the same `advance: human` discipline as the Shape steps:
 **nothing auto-advances**; the engineer owns the merge.
 
 ## Conventions
 
 - `{project-root}` resolves from the project working directory — the **product** repo (the source of
   truth: it holds the story and the build ledger).
-- Code repos are separate git repos under `{project-root}/demo-repos/<repo>/`.
+- Code repos are separate git repos under `{project-root}/demo-repos/<repo>/` (or the registry `path` in
+  `.sdlc/repos.json`).
 - The build ledger uses **shard-then-fold** storage: each ship is its own shard file
   `{project-root}/epics/<epic>/.sdlc/build-log/<story>-<task>-<repo>.json`, so concurrent shippers never
   conflict; readers UNION the folded `build-log.json` with every loose shard, and `yad tidy up` folds
   finished shards back into `build-log.json`. It — like the trust log and build-state — is committed by
   `yad checkpoint` (see Step 3), not by hand.
-- The engineer-review rule reuses `yad-review-gate`: base = at least one `owner` AND one distinct
-  `reviewer`; **escalated** (the PR's Impact & Risk is `high`, or it touches contract/auth/payments) =
-  base PLUS one `domain-owner` per touched domain — the same routing `yad-pr-template`'s
-  `risk-route.sh` prints.
+- The engineer-review rule reuses `yad-review-gate`'s count: `needed = base 1 + risk step` distinct
+  approvers. The risk step comes from the PR's Impact & Risk block — `high` risk +1, a touched contract
+  surface +2 — and from the code repo's risk map on the **base branch**: a change touching a `high`
+  directory +1 (E66). The largest step wins, never the sum. The count is reported, not enforced: branch protection holds the merge (at least 1
+  distinct approver, who should not be the author), and the risk step is advisory. `yad open-pr` shows
+  the count capped by the active people (E72); the check scripts cannot cap it. This is what `yad-pr-template`'s `risk-route.sh`
+  prints. The real merge protection is the platform's branch protection.
 - AI review wiring: `templates/.coderabbit.yaml` → `<repo>/.coderabbit.yaml`.
 
 ## Inputs
 
 - `epic` / `story` / `task` / `repo` — the PR under review (the task branch `feat/<story>-<task>-…`).
 - `action` — `ai-review` | `approve` | `ship` (default `ai-review`).
-- For `approve`: the reviewer `name` and `role` (`owner` | `reviewer` | `domain-owner`), and for a
-  domain owner the `domain`.
+- For `approve`: the reviewer's platform login. No role and no domain.
 
 ## On Activation
 
@@ -58,29 +61,84 @@ never gates. When a pair session backs the approve, you may set `companion.pair:
 
 ### 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.
+and records an approval. Determine the count with `bash checks/risk-route.sh <pr-body-file> origin/<base>`,
+run **in the code repo with the PR's branch checked out** — it reads the body's Impact & Risk block and
+the base branch's `.sdlc/risk-map`, and the larger step wins. On the base branch the change is empty and
+the map adds nothing, so check out the PR branch first. If the repo has no `checks/risk-route.sh`, it is
+not wired yet: run `yad update` for it (that installs `checks/risk-route.sh` and
+`checks/risk-map-check.sh` together). Until then, count from the body alone and say that the map was not
+counted. It prints e.g.
+`ROUTE: 3 approvers = base 1 + contract risk 2 (contract surface touched)`, says branch protection holds the
+merge, not this count (the risk step is advisory and not capped there), and lists the touched domains as a hint for whom to ask. With no risk it
+prints `ROUTE: 1 approver = base 1 (no risk step).` When the map raises a body that says `low`, it
+names the `high` directories and says the two disagree — tell the engineer, and ask the author to fix the
+body if the body is wrong. Record each approval; re-evaluate whether the base
+is met, and report any shortfall against the full count without blocking on it.
+
+**Proven history (E67).** When the change touches a `high` directory, `risk-route.sh` also prints the
+people who have **committed there in the last 30 days**, read from the base branch and with this
+change's own authors left out:
+
+```
+       This change touches src/payments/, so it asks for an approval from someone who has
+       committed there in the last 30 days (its own authors left out):
+  - Alice (@alice)
+  - @carol
+```
+
+A person whose git name holds an `@` is printed as their bare login (`- @carol`), or, when there is no
+login, as `a name that is an e-mail address` or `a name written like a login` — both have NO login. No
+address is ever printed, and a printed `@word` is always a real login, never a git name. A bare `@login`
+counts exactly like a `(@login)` below.
+
+Report it as an ask, never as a block, and use exactly these three answers:
+
+Work down these rows in order and stop at the first that fits — a mixed list, where one person has a
+login and another does not, fits more than one:
+
+| In order | What you see | What to report |
+|---|---|---|
+| 1 | A recorded approver's login is one of the printed logins — a `(@login)` after a name, or a bare `@login` — ignoring upper and lower case | **met** |
+| 2 | The printer says `not read` (a shallow clone, or git could not read the history) | **could not confirm** |
+| 3 | No approver matches, and at least one named person has no login (neither `(@login)` nor a bare `@login`) | **could not confirm** — name everyone printed, and say the names could not be compared |
+| 4 | No approver matches, and every named person has a login (`(@login)` or a bare `@login`) | **short** — name who could meet it |
+
+Rows 2 and 3 matter: an approval records a platform login, while git history records a name, and a login
+only comes from a `noreply` address. Different spellings of a name prove nothing either way, so say the
+ask could not be confirmed rather than inventing a shortfall. Logins are compared without case, because
+a platform login is case-insensitive and the printer shows it as the address wrote it.
+
+With nobody printed at all — `nobody else has committed there in the last 30 days` — there is nobody to
+ask for, and the count stands on its own. That line, and `not read`, are printed higher up in the
+`Risk map (…)` section, not inside the `ROUTE` paragraph above.
+
+**One list, not one per directory.** When a change touches two `high` directories, the people are printed
+as one list: someone who has worked in ANY of them meets the ask. Nothing says which person worked where.
+
 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 (mutating the ship's shard where it lives, or its folded entry if already tidied). 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:
+Recording an approval does **not** ship — shipping is a separate, explicit step. Shape discipline:
 the gate talks only through files; refuse to treat AI review as a human approval.
 
 ### Step 3 — `ship` (merge + record + update state)
 Ship **iff ALL hold**: the check gates pass (Step C), the AI review has run (advisory), and the
 engineer-review rule is satisfied (Step 2). Then:
 - **Merge** the task branch into the repo's default branch (the human performs/authorises the merge).
+- **Check the lane is not skipped (E39)** — read `build-state/<story>.json`. If this repo's lane is
+  `status: skipped`, it was set aside as needing no change: stop, and run
+  `yad unskip <epic> <story> --repo <repo>` before recording a ship, so the two records never say opposite
+  things (`yad doctor` fails that as `lane:…:contradiction`; `yad checkpoint --retro-ship` refuses it).
 - **Record the ship** — write the ship to its own shard
   `epics/<epic>/.sdlc/build-log/<story>-<task>-<repo>.json` (readers union the folded `build-log.json` +
   the loose shards, deduping by (story, task, repo) so a shard wins over a stale folded ship):
   ```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>","engagement":"<verified|none>"}],
-    "companion": {"trailer":true,"cards":true,"chat":false}, "risk": "<low|medium|high>", "shippedAt": "<YYYY-MM-DD>" }
+    "ai_review": "coderabbit (advisory)", "engineer_review": [{"approver":"<platform login>","engagement":"<verified|none>"}],
+    "companion": {"trailer":true,"cards":true,"chat":false}, "risk": "<low|medium|high — the BODY's level>", "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
@@ -91,30 +149,36 @@ engineer-review rule is satisfied (Step 2). Then:
   `epics/<epic>/.sdlc/trust-log/<story>-<repo>-implement-<uid>.json` (or, if the run was already folded
   by `yad tidy up`, into its entry in the folded `trust-log.json`). The human has the last word on the trust signal: a diff merged
   as authored is `approved-unchanged`; one the engineer edited before merge is `approved-with-edits`;
-  a rejected one is `rejected`. This is the evidence that later earns a step its `machine_advance`
+  a rejected one is `rejected`. This is the run record `yad dial` shows the team beside a step's dial
   (it never weakens the merge gate — the engineer still owns the merge).
 - **Commit the machine-written ledgers.** Run `yad checkpoint --push` from `{project-root}` to commit
-  the back-half ledgers just written (the `build-log/` shard, and the `trust-log/` shard /
+  the Build ledgers just written (the `build-log/` shard, and the `trust-log/` shard /
   `build-state/<story>.json` if the story ran through `yad-run`) as one `chore(hub): …` audit-trail
   commit — default branch only, staging the shard dirs (`yad tidy up` folds finished shards later),
-  never a front-half gate file. It is the back-half analogue of the front-half `yad gate` sync. The
+  never a Shape gate file. It is the Build analogue of the Shape `yad gate` sync. The
   same commit also **carries the story `status:` flip** you just wrote (`approved → in-build/shipped`,
   #112) — because that story now has a build-log ship, checkpoint stages `stories/<story>.md` alongside
   the ledgers, so the artifact never drifts from build-log and you never fall back to a raw git-to-main
   push. (The code-repo `tasks.md` is committed in its own repo as usual.)
 
 ### Step 4 — Stop
-Report what shipped and the story's state. Do not advance anything else; the front-half `state.json`
-stays as it was (`ready-for-build`). The build half is recorded in `build-log.json` + the story status.
+Report what shipped and the story's state. Do not advance anything else; the Shape `state.json`
+stays as it was (`ready-for-build`). Build is recorded in `build-log.json` + the story status.
 
 ## Hard rules (build plan §E, Cross-cutting)
 
 - **AI review is advisory, never the authority.** Only a human engineer approval counts toward the gate.
-- **High risk routes to domain owners** — the same escalation as `yad-review-gate` / `risk-route.sh`.
+- **High risk raises the count** — the same count as `yad-review-gate` / `risk-route.sh`, and a `high`
+  directory on the base branch's risk map raises it too; that directory also asks for an approver who has
+  worked there in the last 30 days (E67), reported in the same three states as everything else here:
+  met, short, or could not confirm. The count is advisory — branch protection holds the
+  merge; `yad open-pr` shows the count capped by the active people. There are no domain owners to route to.
+- **The ship record's `risk` is the body's level**, as the author wrote it — not the level the map raised
+  it to. The count is worked out live each time and never stored (the user's decision, 2026-09-18).
 - **Ship only after gates + engineer review.** No gate skipped; the human owns the merge.
 - **Nothing auto-advances.** Step E records human decisions in files; it never machine-advances.
 
 ## Reference
 - The build ledger + story-state rules: `references/ship-and-record.md`.
-- The escalation reused: `../yad-review-gate/SKILL.md`; the routing helper: `../yad-pr-template/`.
+- The count reused: `../yad-review-gate/SKILL.md`; the routing helper: `../yad-pr-template/`.
 - The gates that must pass first: `../yad-checks/references/check-gates.md`.

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

@@ -1,6 +1,6 @@
 # Ship — the build ledger and the story state
 
-Step E (`yad-engineer-review`) closes the build half: AI review (advisory) → engineer review (the human gate) →
+Step E (`yad-engineer-review`) closes Build: AI review (advisory) → engineer review (the human gate) →
 ship. Shipping records the merge and updates the story state so the whole chain is traceable.
 
 ## Two sets of eyes
@@ -10,10 +10,17 @@ ship. Shipping records the merge and updates the story state so the whole chain
    gate. Where CodeRabbit can't run (no remote), an equivalent AI first-pass is run by hand and its
    notes captured.
 2. **Engineer review (the authority).** A human reads the diff against the spec and the acceptance
-   criteria and records an approval. The rule is `yad-review-gate`'s:
-   - **base:** at least one `owner` AND one distinct `reviewer`.
-   - **escalated:** when the PR's Impact & Risk is `high`, or it touches contract/auth/payments — base
-     PLUS one `domain-owner` per touched domain (exactly what `risk-route.sh` prints).
+   criteria and records an approval. The rule is `yad-review-gate`'s count, in distinct approvers:
+   - **base (enforced):** 1 distinct approver, who should not be the author. This holds the merge.
+   - **full count (advisory):** base 1 + a risk step from the PR's Impact & Risk block — `high` risk
+     +1, a touched contract surface +2 — or from the base branch's risk map, where a change touching a
+     `high` directory adds +1 (E66). The largest step, never the sum. Exactly what `risk-route.sh` prints,
+     run in the code repo on the PR's branch.
+     The risk step holds nothing on a code PR: branch protection holds the merge. `yad open-pr` shows
+     the count capped by the active people (E72), for information only. The touched domains it lists are a hint
+     for whom to ask.
+
+   The actual merge protection is the platform's branch protection.
 
 ## The build ledger — shard-then-fold (`epics/<epic>/.sdlc/build-log/` → `build-log.json`)
 
@@ -48,8 +55,8 @@ without the `{ epic, ships }` wrapper):
       "gates": ["spec-link", "contract-check", "build-test-lint"],
       "ai_review": "coderabbit (advisory)",
       "engineer_review": [
-        { "approver": "amelia", "role": "owner", "engagement": "verified" },
-        { "approver": "carol", "role": "reviewer", "engagement": "none" }
+        { "approver": "amelia-dev", "engagement": "verified" },
+        { "approver": "carol-k", "engagement": "none" }
       ],
       "companion": { "trailer": true, "cards": true, "chat": false },
       "risk": "low",
@@ -59,16 +66,16 @@ without the `{ epic, ships }` wrapper):
 }
 ```
 
-This is the back-half analogue of the front half's `approvals.json` — files only, no hidden state, so a
+This is the Build analogue of Shape's `approvals.json` — files only, no hidden state, so a
 future service can drive ship by writing the same records. Like the trust log and build-state, it is a
-machine-written ledger committed by **`yad checkpoint`** (the back-half analogue of `yad gate` sync),
+machine-written ledger committed by **`yad checkpoint`** (the Build analogue of `yad gate` sync),
 not by hand: after recording the ship, `yad checkpoint --push` lands the new `build-log/` shard as a
-`chore(hub): …` audit-trail commit on the default branch (allowlist-scoped to the back-half ledgers,
-never a front-half gate file); `yad tidy up` folds finished shards into `build-log.json` later.
+`chore(hub): …` audit-trail commit on the default branch (allowlist-scoped to the Build ledgers,
+never a Shape gate file); `yad tidy up` folds finished shards into `build-log.json` later.
 
 ### Retroactive ship — a pre-tracking story (#142)
 
-A story that was merged and shipped **before** the back-half ledger existed has no build-log ship, so
+A story that was merged and shipped **before** the Build ledger existed has no build-log ship, so
 `yad checkpoint` can't carry its `status: shipped` flip (the flip is only carried when a ship backs it,
 #112) — leaving a raw `git push origin main` as the only way to land it, against the never-raw-git
 convention. To reconcile it through yad, record a **retroactive** ship, then checkpoint carries the flip
@@ -83,7 +90,7 @@ It writes ONE minimal ship shard marked `retroactive: true` (`task` defaults to
 the normal checkpoint so the story's already-made `status:` flip rides along in the **same** commit. It
 refuses when the story already has a ship **in that repo** (then it isn't pre-tracking there — use the
 normal flow). It does **not** author the story frontmatter — and to keep evidence and the flip atomic (the no-drift
-invariant), it **refuses** unless you have already set a back-half `status:` (`in-build` or `shipped`) in
+invariant), it **refuses** unless you have already set a Build `status:` (`in-build` or `shipped`) in
 `stories/<story>.md`, so a ship shard is never committed while the artifact still says `approved`.
 
 **Where the record lands — it is a shard, not an append to `build-log.json`.** Like every other ship, a
@@ -121,7 +128,8 @@ writing the same ledger at once would otherwise both read "no ship yet" and both
 empty directory (`build-log.json.lock`), so git never sees it; one held by a process that died is
 reclaimed after 30s, and a live one reports `YAD-STATE-006` rather than writing over the other's work.
 
-**Engagement (the Review Companion).** Each `engineer_review` entry carries `engagement: verified | none`
+**Engagement (the Review Companion).** Each `engineer_review` entry names the approver by platform login
+(no role or domain) and 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;
@@ -129,7 +137,7 @@ 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 — writing
 back into the ship's shard where it lives (or its folded entry if the story was already tidied) — the
-back-half **bridge**, the analogue of `yad gate sync`. The signal is gameable by design ("visible, not
+Build **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.
@@ -156,6 +164,7 @@ trailer → story → epic). Resolve that ship by the union rule, not from `buil
 
 1. The three **check gates** pass (Step C) — re-run them on the PR branch if unsure.
 2. The **AI review** has run (advisory; findings surfaced to the engineer).
-3. The **engineer review** rule is satisfied (base or escalated per the Impact & Risk block).
+3. The **engineer review** base is met (1 distinct approver); any shortfall against the full count from
+   the Impact & Risk block is reported, not blocking.
 
 Only then does the human merge and `yad-engineer-review` record it. Nothing auto-advances.