yadflow 3.19.0-next.2 → 4.0.0-next.3

package/skills/yad-checks/references/check-gates.md

@@ -11,10 +11,10 @@ repo uses. Each reads conventions established by earlier steps — it invents no
 | spec-link | the `Task: <story>-<task>` commit trailer; `specs/<story>/link.md` | `yad-implement` (trailer), `yad-spec` (link.md) |
 | contract-check | changed files under `specs/<story>/contracts/`; the `Contract-Change: yes` trailer; `link.md`'s pinned `contract-lock`; the product repo's `contract-lock.json` | `yad-architecture` (lock), `yad-spec` (slice + link), `yad-implement` (trailer) |
 | build/test/lint | the repo's configured package manager running `lint` / `build` / `test` | the repo |
-| lineage-check | the `Task:` trailer → `link.md` (`epic` + `product-repo`); the owning epic's `kind`/`parent` frontmatter in the hub | `yad-spec` (link.md), `yad-change` (lineage frontmatter) |
-| epic-open | the `Task:` trailer → `link.md` → the hub epic's `stories/*.md` `status:` (sealed = all `shipped`) | `yad-engineer-review` (story status), `yad-change` (the change-epic) |
-| reconcile-debt | the `Task:` trailer → `link.md` → the hub epic's `thread`; every thread epic's `reconcile-debt.json` | `yad-change` (opens hotfix debt) |
-| verified-commits | each commit's platform signature-verification status; the author email vs `.sdlc/verified-authors` | hub roster `email` fields (`yad check --fix` generates the allowlist) |
+| lineage-check | the `Task:` trailer → `link.md` (`epic` + `product-repo`); the owning epic's work-item type (`kind:`, then `type:`) and `parent` frontmatter in the Product | `yad-spec` (link.md), `yad-change` (lineage frontmatter) |
+| epic-open | the `Task:` trailer → `link.md` → the Product epic's `stories/*.md` `status:` (sealed = all `shipped`) | `yad-engineer-review` (story status), `yad-change` (the change-epic) |
+| reconcile-debt | the `Task:` trailer → `link.md` → the Product epic's `thread`; every thread epic's `reconcile-debt.json` | `yad-change` (opens hotfix debt) |
+| verified-commits | each commit's platform signature-verification status | the platform (GitHub/GitLab "Verified"); no author allowlist since E62 |
 | commit-message | each non-merge commit's subject + trailer block | `yad-commit` / `CONTRIBUTING.md` (`config.yaml build.commit_subject_style`) |
 | pr-title | the PR/MR title (from the CI event payload) | `yad-pr-template` (`config.yaml build.pr_title_style`) |
 | pr-template | the PR/MR body (from the CI event payload) | `yad-pr-template` (the committed PR/MR template) |
@@ -66,7 +66,36 @@ own CI runs, plus an assertion that each one actually *assigns* `BASE` from it.
 - **Fails closed** if `<base>` can't be resolved — an undiffable range must never report "no surface
   change" and silently green-light a bypass. `<base>` is optional — see
   [Resolving `<base>`](#resolving-base-every-gate-that-takes-one).
+- **Refuses any symlink or submodule under `specs/`** (E115), right after the base check and before
+  any surface rule. The gate reads
+  paths, and a link lets the content live where no path under `specs/` names it: a symlink at
+  `specs`, `specs/<story>` or `specs/<story>/contracts` hid the slice from every rule, and so did every
+  later edit to the link's target. A symlinked `link.md` redirects the lock pin the fidelity check
+  reads. The check reads the **tree at HEAD** (`git ls-tree -r -z --full-tree HEAD`), not the diff, so
+  a link merged before this check existed fails **every PR** in the repo until one PR removes it. It
+  matches `specs` **without case**: on macOS and Windows `Specs/` is the same folder, and git's path
+  filter matches exact bytes only. A top folder spelled any other way than `specs` (`Specs/`, `SPECS/`)
+  is refused too, even when it holds plain files — the surface rules below are spelled in lowercase and
+  would never see them. `ſpecs` (long s) counts as a second spelling: APFS folds it into `specs`.
+  The same holds further down: a `contracts` folder spelled any other way (`Contracts/`, `CONTRACTS/`,
+  `contractſ/`) is refused, and so are two story folders that differ only in ASCII case or the long s
+  (`specs/EP-x-S01/` and `specs/ep-x-s01/`) — one folder on a Mac, two to rules that read exact bytes.
+  Other letters are **not** caught: `specs/EP-démo-S01/` beside `specs/EP-DÉMO-S01/`, or the same name in
+  NFC and NFD form, is one folder on a Mac and two here. The surface rule still matches both, so the
+  trailer is still required; at worst the lock check reads no `link.md` and is deferred — something a
+  PR can already do by leaving `link.md` out (E117).
+  A file named exactly `specs` is refused too: the folder has to go there.
+  **So a code repo that already has a `Specs/` folder or submodule (an iOS test folder, say), or a
+  top-level file named `specs` in any case, fails every PR until it is renamed** — on a Mac checkout,
+  `yad-spec` writing `specs/<story>/` would land inside it. `SPECS.md`, `Specs-old/` and a nested
+  `foo/specs/` are not that folder and pass. A git that cannot read the tree fails the gate with a line
+  that says so.
+  `yad-spec` writes real files, so nothing legitimate lives there as a link. Removing a link under
+  `contracts/` is a change to the surface and needs `Contract-Change: yes`; on a lockless epic it takes
+  the removal hatch below. `yad doctor` warns `checks:symlink-blind` for an older copy without this check.
 - Computes the changed files in `<base>..HEAD`.
+- The surface is `specs/<story>/contracts` **and** everything under it: a path that IS
+  `specs/<story>/contracts` (a link being removed) counts too.
 - If **nothing** under `specs/*/contracts/**` changed → **PASS** (normal implementation only *consumes*
   the contract).
 - If the surface slice changed:
@@ -85,9 +114,20 @@ own CI runs, plus an assertion that each one actually *assigns* `BASE` from it.
   - A lock the gate can **read but not parse** (truncated, half-written, or a changed schema — no
     `"hash": "sha256:…"`) **FAILS**. It used to short-circuit the comparison into the "hash matches"
     note, i.e. the gate affirmatively reported a match it never made.
-- The changed-file list is read with `core.quotePath=false`. With git's default, a path holding a
-  non-ASCII byte comes back quoted and octal-escaped, so a slice like `specs/EP-démo-S01/contracts/…`
-  never matched the surface pattern and an undeclared widening passed untouched.
+- The changed-file list is read with `git diff --no-renames --name-only -z` (E114):
+  - `--no-renames` lists a rename by **both** paths — a delete of the old one and an add of the new.
+    Without it git names a rename by its new path only, so `git mv specs/S1/contracts/api.md
+    docs/api.md` took the slice off the surface and passed with no `Contract-Change` trailer.
+  - `-z` (NUL-separated) means git never quotes a path. By default git quotes a path holding a
+    non-ASCII byte, and it quotes one holding a `"` or a tab even with `core.quotePath=false` — so a
+    slice like `specs/EP-démo-S01/contracts/…` never matched the surface pattern.
+  - The script runs with `LC_ALL=C` (bytes, not characters), so a file name that is not valid UTF-8
+    cannot make GNU grep drop the list on Linux CI.
+  - The list of **deleted** slice paths (the lockless escape hatch above) is built the same way, so
+    moving a slice out of `contracts/` under a lockless epic is still a removal.
+  - `yad doctor` warns `checks:rename-blind` when an installed `checks/contract-check.sh` (or
+    `checks/backfill-check.sh`) in the Product or a connected repo still lists a rename by one path —
+    a copy changed by hand, which `yad check --fix` keeps.
 - This enforces the Phase 2 rule: the shared surface is owned upstream and is never widened from inside
   a code repo. The hash recipe is in `../yad-architecture/references/contract-format.md`.
 
@@ -117,7 +157,7 @@ own CI runs, plus an assertion that each one actually *assigns* `BASE` from it.
   release; generated files remain managed instead of accumulating consumer-specific edits. The
   variable is read by the code repo's `yad-checks` workflow only (on GitHub the build/test/lint job;
   in the GitLab fragment it sets the `node:` image of every `yad-*` gate job, which all share one
-  anchor) — the hub-side workflows run the `yad` CLI, not the repo's toolchain, and keep their own
+  anchor) — the Product-side workflows run the `yad` CLI, not the repo's toolchain, and keep their own
   pinned Node. A declared `packageManager` needs
   Corepack, which ships with Node 18 through 24 (Node 25+ dropped it) and, before 18.20.7 / 20.19 /
   22.14, carries registry keys too old to verify anything published since 2025 — so the override
@@ -150,30 +190,39 @@ runner. Real repos substitute their own eslint/tsc/jest — the gate only calls
 
 ## 4. verified-commits (`templates/checks/verified-commits.sh`)
 
-No unverified commits from unverified users reach merge — on the product hub and on every connected
-repo. For each commit in `<base>..HEAD`, two independent checks:
+No unsigned commits reach merge — on the Product and on every connected repo. For each commit in
+`<base>..HEAD`, one check:
 
 - **Verified signature** — the platform must mark the commit's signature verified (the GitHub/GitLab
   "Verified" badge: signed with a GPG/SSH key registered to the account owning the author email).
   Read via `gh api repos/{owner}/{repo}/commits/<sha>` (GitHub) or the commits/signature API (GitLab).
-- **Known author** — the commit's **author email** must appear in `.sdlc/verified-authors`, generated
-  by `yad check --fix` from the hub roster's `email`/`emails` fields plus hub.json's
-  `verified_authors` list (edit hub.json, never the generated file). Only the author is checked:
-  platform-generated squash commits keep the PR author (who is on the roster). Two identities are
-  **allowlist-waived but still signature-covered**: the `yad-gate-sync` bot, and any **merge commit**
-  (2+ parents) — a merge's author is whoever pressed merge (often a platform noreply), not a roster
-  human, and its content already passed the PR gate suite. This waiver matters for the push-on-default
-  `yad-update-guard` (§9), which — unlike this PR-triggered gate — sees merge commits.
-  A merge commit is **additionally signature-waived when it introduces no content of its own** (its
-  combined diff — `git diff-tree --cc` — is empty, i.e. no conflict-resolution or evil-merge hunks):
-  every change it carries already lives in an individually author+signature-checked parent, so there
-  is nothing to protect. This unblocks **self-hosted GitLab**, which does not sign UI-created merge
-  commits (the signature API returns 404) — without it every routine merge would red the branch. A
-  merge that *does* introduce content of its own still requires a verified signature (fail-closed),
-  so an evil merge pushed direct-to-default cannot smuggle in unverified changes.
-
-Degradation is explicit, never silent: a missing allowlist SKIPs the author check with a warning
-(configure roster emails, re-wire); no GitHub/GitLab remote SKIPs the signature check (the badge is a
+
+**There is no author allowlist** (E62). yadflow keeps no list of people: write access to the repo
+decides who can author, and the signature proves which platform account made the commit. `yad check --fix`
+and `yad setup` no longer generate `.sdlc/verified-authors`, and no gate reads it or hub.json's
+`verified_authors` any more (`SDLC_VERIFIED_AUTHORS` is gone too). When an old `.sdlc/verified-authors`
+file is still on disk, the gate prints:
+
+```
+note [verified-commits]: .sdlc/verified-authors is no longer read — write access to the repo decides who can author; the signature is still required.
+```
+
+`yad doctor` warns `people:verified-authors-unused` for the same leftover data; nothing deletes it.
+The old allowlist waivers for the `yad-gate-sync` bot and for merge commits are gone too, because there
+is no allowlist left to waive. A bot commit inside the checked range needs a Verified signature like any
+other commit.
+
+**Content-free merge exemption** (unchanged). A merge commit (2+ parents) is **signature-waived when it
+introduces no content of its own** (its combined diff — `git diff-tree --cc` — is empty, i.e. no
+conflict-resolution or evil-merge hunks): every change it carries already lives in an individually
+signature-checked parent, so there is nothing to protect. This unblocks **self-hosted GitLab**, which
+does not sign UI-created merge commits (the signature API returns 404) — without it every routine merge
+would red the branch. A merge that *does* introduce content of its own still requires a verified
+signature (fail-closed), so an evil merge pushed direct-to-default cannot smuggle in unverified changes.
+This matters for the push-on-default `yad-update-guard` (§9), which — unlike this PR-triggered gate —
+sees merge commits.
+
+Degradation is explicit, never silent: no GitHub/GitLab remote SKIPs the signature check (the badge is a
 platform concept — this keeps local runs and tests meaningful); an unreachable platform API **fails
 closed** with guidance. GitLab CI needs a `GITLAB_TOKEN`/`SDLC_API_TOKEN` variable with `read_api` —
 `CI_JOB_TOKEN` cannot read the signature API.
@@ -193,8 +242,8 @@ non-merge commit in `<base>..HEAD`:
   `COMMIT_TYPES`) and **no trailing period** — mirroring `cli/commit.mjs` `buildCommitMessage`.
 - **Trailers**, when present, appear in the fixed order `Task → Contract-Change → Co-Authored-By`.
 - Merge/squash commits (2+ parents) are skipped — their platform-generated subjects are not authored.
-- **Profiles** (`--profile code|hub`): the subject rule is identical on both; the gate never requires
-  the `Task:` trailer (spec-link owns that on code repos; hub commits are not task-scoped).
+- **Profiles** (`--profile code|hub|product`): the subject rule is identical on both; the gate never requires
+  the `Task:` trailer (spec-link owns that on code repos; Product commits are not task-scoped).
 - **Fails closed** when `<base>` can't be resolved.
   `<base>` is optional — see [Resolving `<base>`](#resolving-base-every-gate-that-takes-one).
 
@@ -209,14 +258,20 @@ from the event payload):
 - `--profile hub` → splits by the PR/MR **head branch** (passed via `--head`, injected by CI):
   - `review/EP-*` head (or no `--head` — stays strict) → a Shape artifact-review title
     `review: <artifact> (EP-<slug>)`, the shape `yad gate open` creates.
-  - any other head → a tooling/code change to the hub itself, so it follows the `code` convention (a
-    Conventional-Commits subject). This is what lets a PR that changes the hub's own workflows/checks
+  - any other head → a tooling/code change to the Product itself, so it follows the `code` convention (a
+    Conventional-Commits subject). This is what lets a PR that changes the Product's own workflows/checks
     pass — it has no EP artifact to review.
   - **Anti-bypass guard.** The branch name alone is not trusted: a non-review head that actually
-    changes Shape artifacts (any path under `epics/**`) **FAILS** — those changes must go through
+    changes Shape artifacts (any path under `epics/**` or `foundation/**`) **FAILS** — those changes must go through
     a `review/EP-*` PR and the artifact-review workflow. CI passes the PR's changed paths via
     `--changed <file>` (computed from the diff against the base ref); without that list (a direct
-    by-hand caller) the guard is inert and the branch split alone applies.
+    by-hand caller) the guard is inert and the branch split alone applies. A step owner file
+    (`epics/<epic>/.sdlc/owners/<step>.json`, `foundation/.sdlc/owners/…`, written by `yad assign`,
+    E47) is not a Shape artifact: a PR that changes only owner files passes on any branch. The
+    workflow builds the list with `--no-renames` (and `core.quotePath=false`), so a rename INTO
+    `owners/` still lists the artifact it removed. A path git still C-quotes (a `"`, `\`, tab or
+    newline in its name) counts as an artifact change and never as an owner file. Both greps run with
+    `LC_ALL=C grep -a`, so a path with bytes that are not valid UTF-8 is never dropped from the list.
 
 ## 7. pr-template (`templates/checks/pr-template.sh`)
 
@@ -228,11 +283,11 @@ catches a free-form description that bypassed it:
 - `--profile hub` → splits by the PR/MR **head branch** (passed via `--head`, injected by CI):
   - `review/EP-*` head (or no `--head`) → requires the artifact-review template: `## Artifact under
     review`, `## Impact & Risk (front-half)` (or `(Shape)`), `## Checklist`, and a `Risk tags:` line.
-  - any other head → a hub tooling PR, so it requires the `code` task template (`## Summary`,
+  - any other head → a Product tooling PR, so it requires the `code` task template (`## Summary`,
     `## Impact & Risk`, `## Checklist`, filled `Risk level:`).
   - **Anti-bypass guard** (same as pr-title): a non-review head that changes Shape artifacts
-    (`epics/**`, detected from the CI-supplied `--changed <file>` list) **FAILS** — artifact changes
-    must go through a `review/EP-*` PR.
+    (`epics/**` or `foundation/**`, detected from the CI-supplied `--changed <file>` list) **FAILS** — artifact changes
+    must go through a `review/EP-*` PR. Step owner files alone do not count (E47).
 
 **GitLab truncates the description this gate reads.** `$CI_MERGE_REQUEST_DESCRIPTION` stops at **2700
 characters**, so a long but perfectly valid MR can lose a required section *before the gate sees it* —
@@ -251,14 +306,14 @@ both shipped:
 After the contract locks and code ships, a change must not mutate a locked artifact — it becomes a new
 epic threaded to its parent (`config.yaml` `change:`). These three gates keep that discipline. All three
 resolve the owning epic the same way: `Task:` trailer → `specs/<story>/link.md` (`epic` + `product-repo`)
-→ the hub epic. All **fail closed** on an unresolvable base; all are **per commit**; `ci|chore|build|test`
+→ the Product epic. All **fail closed** on an unresolvable base; all are **per commit**; `ci|chore|build|test`
 commits **with no `Task:` trailer** are exempt — like spec-link, the exemption waives the requirement
 for an owning epic, never the validity of one that is claimed, so a maintenance subject cannot buy a
-pass past the sealed-epic / orphan-thread / frozen-thread checks. When the **product hub is not reachable** from CI (the usual case for a code-repo
-PR), each degrades to a **PASS-with-note** — the hub-side check (`yad doctor` / `yad reconcile`) covers
+pass past the sealed-epic / orphan-thread / frozen-thread checks. When the **Product is not reachable** from CI (the usual case for a code-repo
+PR), each degrades to a **PASS-with-note** — the Product-side check (`yad doctor` / `yad reconcile`) covers
 that path, and spec-link still proves the story link.
 
-**Resolving `product-repo` (shared by all four hub-reading gates, contract-check included).** An
+**Resolving `product-repo` (shared by all four Product-reading gates, contract-check included).** An
 **absolute** value is used as-is; a **relative** value is joined to the `link.md`'s own directory,
 `specs/<story>/`, falling back to a repo-root reading when only that resolves (what contract-check
 historically did, so `link.md` files written for it keep working). The `link.md` itself is read from
@@ -269,9 +324,11 @@ gate now **prints that note**, so a deferred check is never mistaken for a passe
 duplicated verbatim across the four scripts (they are standalone by design) and a test asserts the
 four copies stay byte-identical.
 
-- **lineage-check** — reads the hub epic's `kind`/`parent` frontmatter. A `feature` (genesis) epic
+- **lineage-check** — reads the Product epic's work-item type and `parent` frontmatter. The type has
+  two names and the gate reads `kind:` first, then `type:` — the same order the CLI uses, asserted by a
+  table test in `cli/test-checks.mjs`. A `feature` or `chore` (genesis) epic
   passes. A `change`/`defect`/`hotfix` epic **FAILS** unless it declares a `parent:` that resolves to a
-  real `epics/<parent>/` in the hub (no orphan threads). This is the "every code change has an owning
+  real `epics/<parent>/` in the Product (no orphan threads). This is the "every code change has an owning
   epic in a thread" enforcement, layered on spec-link.
 - **epic-open** — an epic is **sealed** iff it has ≥1 story and **every** `stories/*.md` `status:` is
   `shipped`. A commit whose owning epic is sealed **FAILS**: new behaviour cannot mutate a shipped epic;
@@ -284,7 +341,7 @@ four copies stay byte-identical.
 ## 9. yad-update-guard (`templates/github/yad-update-guard.yml`, `templates/gitlab/yad-update-guard.gitlab-ci.yml`)
 
 The **integrity gate for direct pushes to the default branch**. `yad update --push` (`cli/update-commit.mjs`)
-commits the applied SDLC drift (skills, gate scripts, CI wiring, `verified-authors`) and pushes it
+commits the applied SDLC drift (skills, gate scripts, CI wiring) and pushes it
 **straight to the default branch with no PR/MR** — so the `pull_request`/`merge_request` gate suite never
 fires. This workflow is the "skipped from CI **except** verified-commits + the pattern gate" contract: on a
 **push** to the default branch it runs **only** `verified-commits` and `commit-message` over the pushed
@@ -295,7 +352,7 @@ strictly-good invariant. Normal PR merges sail through — merge commits are pla
 `commit-message` skips merges. The `yad update --push` commit itself carries **no `[skip ci]`** (unlike the
 machine-state `yad checkpoint`/`gate ci` commits) precisely so this guard runs on it.
 
-Wired into **every connected repo and the hub** (`REPO_WIRING`/`HUB_WIRING` in `cli/manifest.mjs`). On
+Wired into **every connected repo and the Product** (`REPO_WIRING`/`PRODUCT_WIRING` in `cli/manifest.mjs`). On
 GitHub it is a self-contained workflow (`.github/workflows/yad-update-guard.yml`, marker `# yad-managed:
 yad-checks`), gated to the default branch by a job-level `if: github.ref_name ==
 github.event.repository.default_branch`. On GitLab it is an includable fragment
@@ -307,12 +364,114 @@ include line exists** — `yad update --push` warns when it pushes to a gitlab r
 lacks it.
 
 **Prerequisites / caveats.** Direct pushes to the default branch must be permitted for the committer
-(adjust branch protection). The commits `yad update --push` creates must be **signed** and their author
-**allowlisted**, or this guard rejects them — `yad update --push` runs a pre-flight that warns when local
-commit signing is unset or the operator's git email is not in `.sdlc/verified-authors`. Ordinary PR merges
-pass (merge commits are allowlist-waived + Verified), but a **rebase-merge** recreates the PR commits
+(adjust branch protection). The commits `yad update --push` creates must be **signed**, or this guard
+rejects them — `yad update --push` runs a pre-flight that warns when local commit signing is off. Ordinary
+PR merges pass (merge commits are Verified, or content-free and signature-waived), but a **rebase-merge**
+recreates the PR commits
 without the platform signature, so a rebase-merge team should sign commits or not wire this guard.
 
+## 10. risk-map (`templates/checks/risk-map-check.sh`) — advisory
+
+Reads the code repo's **risk map**, `.sdlc/risk-map`: one line per directory giving it a level (`high`,
+`medium`, `low`, or `unset`), marked `guessed` (an AI agent filled it) or `confirmed` (a person checked
+it), and **no names** (E65). The format, the rubric and who may change what:
+`../yad-connect-repos/references/risk-map.md`. The rules have a twin in `cli/riskmap.mjs`
+(`yad risk-map check`, `yad doctor`); a test runs both over the same repos and compares the output.
+
+It **always exits 0**: the count it prints is reported, never enforced — the platform's branch
+protection holds a Build merge. It cannot apply the capacity cap (E72) either: the cap needs the
+Product's count of active people, which a code repo's CI does not have; `yad open-pr` shows the capped
+count. So a stale map must never block a merge. It prints `WARN [risk-map] <code> <target>: …` for:
+
+| Code | When |
+|---|---|
+| `uncovered` | a file this change adds or edits that no line covers — names the directory to add. A directory a line cannot hold (`app/[slug]/`) names its parent instead; a top-level one (`my docs/`) says to rename it |
+| `dead` | a line whose directory holds no file (`./`: no file at the root) — on every change, until fixed |
+| `unset` / `guessed` | a line this change touches that has no level yet, or whose level is still a guess |
+| `unreadable` / `names` / `duplicate` | a line that is not `<dir>/ <level> <state>`, names a person (a word starting `@`, `@org/team` included — a word ending in `/`, like `@types/`, is a directory), or repeats a directory |
+| `header` / `version` | no `# yad-risk-map v1` first line (read as v1), or a newer version (nothing is read) |
+| `map-edited` | the change edits the map itself, which decides how much review later changes need |
+
+The change is `git diff --name-only -z --diff-filter=ACMRT <base>...HEAD` (T: a file turned into a symlink is an edit) — **three dots**, measured from
+where the branch left the base, so commits the base gained since are never blamed on this change (the
+blocking gates use two dots; this one only warns about what the change touches). A deleted file is never
+asked about. The repo is `git ls-files -z`. Both lists are read NUL-separated, so a path holding `"`, `\`
+or a tab arrives as it is, never quoted by git. A base that does not resolve, or shares no history with HEAD (a shallow clone), is a note, not a failure:
+the map's own lines are still checked. A repo with no map gets one note and passes — **unless this change deleted
+the map**, which warns `map-edited`: a rename away from `.sdlc/risk-map`, and the map replaced by a folder or by a symlink that leads nowhere or to a folder, count as a delete. A symlink to a real file is not — `[ -f ]` follows it, so the check reads the link's target as the map and says `edits`. Deleting some other file under a *folder* named `.sdlc/risk-map/` gets the plain no-map note, not `map-edited`. Outside a git repo it
+prints a note and exits 0. **Known limits:** a path holding a newline reads differently here than in
+`yad risk-map check` — git's NUL-separated list has to become lines for macOS awk — and such a directory
+cannot have a line anyway. A path whose bytes are not valid UTF-8 differs too: this check compares bytes
+(`LC_ALL=C`), while the CLI decodes bad bytes as U+FFFD. **The map file is not wired** — it is the
+team's, so `yad update` never owns or overwrites it; only the check is.
+
+**The count (E66).** Before the warnings it prints one line saying how many approvers the change asks for:
+
+```
+COUNT [risk-map]: 2 approvers = base 1 + high risk 1 (high on origin/main: src/payments/ (guessed)) — reported, not enforced: branch protection holds the merge.
+COUNT [risk-map]: 1 approver = base 1 — nothing this change touches is high on origin/main.
+```
+
+- The map is read from the **base branch's tip** (`git show <base>:.sdlc/risk-map`), never from the
+  change's copy — so a change cannot lower its own count by editing or deleting the map. The warnings
+  above still read the change's copy, because they are about keeping that copy true.
+- Only a real file on the base is read. A symlink or a folder with that name is treated as no map.
+- The change's files for the count are `git diff --name-only -z --no-renames <base>...HEAD`, **with no
+  filter**: a deleted file, and a file moved away, count where they were. Deleting code in a `high`
+  directory is a `high` change. (The warnings keep `--diff-filter=ACMRT`: a deleted file cannot be
+  uncovered.)
+- A `guessed` level counts as a `confirmed` one. `medium` is printed on its own line and adds nothing.
+  An `unset` line, and a file no line covers, add nothing.
+- The base has no map: `1 approver = base 1 — '<base>' has no .sdlc/risk-map, so no directory adds a step.` The base does not resolve,
+  shares no history with HEAD, or holds a map for a newer version: **no COUNT line**, and a note that the
+  count is unknown, not zero.
+
+**Who can meet the ask (E67).** Under the count, the check names the people who have committed in the
+last 30 days in the `high` directories this change touches. With two such directories it is ONE list:
+someone who has worked in any of them meets the ask, and the output never says who worked where.
+
+```
+  ask one of these (committed there in the last 30 days, this change's own authors left out): Alice (@alice)
+  nobody else has committed there in the last 30 days — the count above still stands.
+  who has worked there lately: not read — this is a shallow clone — it does not hold the history of those directories.
+```
+
+- The history is the **base branch's** (`git log <base> --since='30 days ago' --no-merges`), so a change
+  cannot add its own; git filters on the **committer** date. The change's own authors are left out,
+  because an approval has to come from someone else, and a robot (`…[bot]`) is never listed.
+- **Git applies the map, and no file name is ever read back.** One query runs per `high` directory, in
+  map order, carrying pathspecs that say what the map means by it: the directory, minus every listed
+  directory below it — the deepest line decides, and each of those answers for itself in its own query
+  (an exclude beats a later include, so they cannot share one). `./` is the files AT the root
+  (`:(glob)*`, because `*` never spans `/`). Git then returns author records only. Reading a list of
+  file names back was what let a quoted path, a name holding a newline, or a merge's simplified path
+  list name the wrong person; there is no list to misread now.
+- A person is their git **name**, plus `(@login)` only when the commit address is a platform `noreply`
+  one. No e-mail address is ever printed. A name holding an `@` is replaced: by the bare login when
+  there is one (`WHO carol @carol`), else by `a name that is an e-mail address` or `a name written like a
+  login` — so a printed `@word` is always a real login.
+- A **shallow clone** says "not read", never "nobody": it holds only the newest commits, and reading
+  that as "nobody has worked here" would drop the ask instead of raising it. Wired CI checks out the
+  full history (`fetch-depth: 0`, `GIT_DEPTH: 0`), so this is a local or host-overridden case.
+- A side branch whose merge kept the other side still counts (`--full-history`): git otherwise simplifies
+  a path-filtered log and hides it.
+- **Known limit:** git's date-limited walk stops at the first commit older than the window on a chain,
+  so a repo whose commit dates run out of order (a wrong clock, an imported history) can hide people
+  behind that commit. It under-lists, so the printed people are always real ones.
+
+`risk-map-check.sh --level [<base>]` prints the same result as machine lines (`BASE`, `UNKNOWN`, `NOMAP`,
+`FILES`, `LEVEL`, `DIR <dir> <level> <state>`, `WHO <login|-> <name>`, `HISTNONE` — the history was read
+and held nobody — and `HISTUNKNOWN <why>`) for `checks/risk-route.sh`, which joins it with the PR
+body. One awk program serves both the warnings and the count. Its twin is `changeLevel` in
+`cli/riskmap.mjs`, and a parity test compares the two. **Known limits:** like every check here, the
+script runs from the PR's own checkout, so a PR can edit the script itself; that is harmless only because nothing
+blocks on the count — the Build count stays reported, and branch protection holds the merge (E72). And, as for the warnings, a path holding a newline is
+split in two here but kept whole by `changeLevel`, so the bash count can read its second half as a file
+at the root; the error can only raise the count, never lower it. (The E67 history is free of that class:
+it reads no file names at all.) If git itself fails, each step of the
+count says "not counted"; the E65 warnings half is not guarded the same way, so a failing `git diff` or
+`git ls-files` there can still end the script with git's exit code.
+
 ## CI wiring (both platforms)
 
 The gates run identically under either CI; the config just invokes the scripts with the PR/MR base.
@@ -326,8 +485,8 @@ The gates run identically under either CI; the config just invokes the scripts w
   re-runs `pr-title`/`pr-template`, not the whole suite. The pattern jobs
   read the title/body from the event payload: `pr-title` takes `${{ github.event.pull_request.title }}`
   and `pr-template` writes `${{ github.event.pull_request.body }}` to a temp file. All `--profile code`.
-  The Phase 6 thread gates (`lineage-check`, `epic-open`, `reconcile-debt`) run as their own jobs with
-  `fetch-depth: 0`, the same `origin/${{ github.base_ref }}` base. The build/test/lint checkout also
+  The Phase 6 thread gates (`lineage-check`, `epic-open`, `reconcile-debt`) and the advisory `risk-map`
+  check run as their own jobs with `fetch-depth: 0`, the same `origin/${{ github.base_ref }}` base. The build/test/lint checkout also
   uses `filter: blob:none`; its installer follows `package.json#packageManager`, and `NX_BASE` /
   `NX_HEAD` carry the exact base/head SHAs so Nx affected commands evaluate the PR rather than a
   stale default. `YAD_NODE_VERSION` is read from GitHub repository variables with `22` as the default.
@@ -375,37 +534,43 @@ break nor reorder them; job names are `yad-`prefixed to avoid collisions.
 **Idempotent.** The two markers plus the include-entry check make a re-run a no-op. This is how a repo
 that already had its own pipeline keeps it and still gains the gates.
 
-## Wiring the hub (`repo: hub`)
+## Wiring the Product (`repo: hub`)
 
-The product hub is itself a repo on a platform (recorded in `.sdlc/hub.json` by
+The Product is itself a repo on a platform (recorded in `.sdlc/hub.json` by
 `yad-connect-repos action: detect-hub`). `wire repo: hub` targets `{project-root}` and uses the same
-merge-not-clobber logic, with a **hub-flavored gate set** appropriate to a "thinking" repo (it has no
-`specs/` or `package.json` build):
+merge-not-clobber logic, with a **Product-flavored gate set** appropriate to a "thinking" repo (it has no
+`specs/` or `package.json` build). **What yadflow wires today** (`PRODUCT_WIRING`): `commit-message`,
+`pr-title`, `pr-template` and `ledger-guard` in `yad-hub-checks`, `verified-commits` in its own workflow,
+and the `yad-update-guard`. The three below are **not shipped** — they are scripts a team writes itself if
+it wants them:
 - **owner-set** — every `epic.md` (and forward artifact) under `epics/EP-*/` carries an `owner`.
 - **contract-locked** — where an epic has a `contract.md`, its surface hash matches
   `.sdlc/contract-lock.json` (reuse the recipe in
   `../yad-architecture/references/contract-format.md`).
-- **approvals-present** — an epic at `ready-for-build` has the approvals its gate rule requires recorded
-  in `.sdlc/approvals.json` (the same predicate `yad-review-gate` enforces).
+- **approvals-present** — an epic at `ready-for-build` has the approvals the gate rule requires recorded
+  in `.sdlc/approvals.json`: at least 1 approver (the author is not checked here — the platform's own
+  rules stop self-approval on GitHub, and on GitLab when its settings say so; the same predicate
+  `yad-review-gate` enforces; the risk step of the full count, capped by the active people (E72), is
+  reported beside it and gates nothing).
 
-These are advisory checks on the hub's own PRs (the Shape review PRs the verified ledger opens); they keep
-the hub's artifacts internally consistent. The hub never runs the code-repo `spec-link`/`build-test-lint`
-gates. Author the hub gate scripts under the hub's `checks/` following the same CI-agnostic-bash pattern.
+These are advisory checks on the Product's own PRs (the Shape review PRs the verified ledger opens); they keep
+the Product's artifacts internally consistent. The Product never runs the code-repo `spec-link`/`build-test-lint`
+gates. Author the Product gate scripts under the Product's `checks/` following the same CI-agnostic-bash pattern.
 
-The hub **does** run the verified-commits gate — `yad check --fix` installs `checks/verified-commits.sh`
+The Product **does** run the verified-commits gate — `yad check --fix` installs `checks/verified-commits.sh`
 plus a standalone workflow (`templates/github/yad-verified-commits.yml` →
 `.github/workflows/yad-verified-commits.yml`, or the GitLab fragment
 `templates/gitlab/yad-verified-commits.gitlab-ci.yml` → `.gitlab/ci/yad-verified-commits.yml` +
 its one include line) whenever `.sdlc/hub.json` has a platform with a verified ledger. So the
-Shape review PRs are held to the same rule as code-repo PRs: signed, known authors only.
+Shape review PRs are held to the same rule as code-repo PRs: platform-Verified signatures only.
 
-The hub **also** runs the three pattern gates (`commit-message`, `pr-title`, `pr-template`) with
+The Product **also** runs the three pattern gates (`commit-message`, `pr-title`, `pr-template`) with
 `--profile hub`. The pattern gates split by the PR/MR **head branch** (passed via `--head`): a
 `review/EP-*` head is a Shape review PR — Conventional-Commits commit subjects, a
-`review: <artifact> (EP-<slug>)` title, and the hub artifact-review template body; **any other head is
-a tooling/code change to the hub itself** and follows the `code` convention (a Conventional-Commits
-title + the code task template), so a PR that changes the hub's own workflows/checks can pass.
-`yad check --fix` installs the same `checks/*.sh` scripts plus a standalone hub workflow
+`review: <artifact> (EP-<slug>)` title, and the Product artifact-review template body; **any other head is
+a tooling/code change to the Product itself** and follows the `code` convention (a Conventional-Commits
+title + the code task template), so a PR that changes the Product's own workflows/checks can pass.
+`yad check --fix` installs the same `checks/*.sh` scripts plus a standalone Product workflow
 (`templates/github/yad-hub-checks.yml` → `.github/workflows/yad-hub-checks.yml`, or the GitLab fragment
 `templates/gitlab/yad-hub-checks.gitlab-ci.yml` → `.gitlab/ci/yad-hub-checks.yml` + its one include
 line). Code repos run the same three with `--profile code` inside the main `yad-checks` workflow.
@@ -426,11 +591,70 @@ be reverted before the review PR/MR can go green.
 | exit 0 | allow |
 | exit 2 | deny — the reason is on stderr, for the agent to read |
 
-Claude Code's `PreToolUse` protocol is exactly that (exit 2 blocks the call and feeds stderr back to
-the model), so `.claude/settings.json` wires it with no adapter logic. Any harness that can run a
-command and read those two exit codes can use the same script.
+Two harnesses match that contract, and `yad check --fix` wires both:
 
-**Layering.** `hooks/ledger-guard.sh` is only the adapter: it locates `yad` (`$YAD_BIN` → the hub's
+| Harness | File | Event | Command |
+|---|---|---|---|
+| Claude Code | `.claude/settings.json` | `PreToolUse` | `"$CLAUDE_PROJECT_DIR/hooks/ledger-guard.sh"` |
+| Cursor | `.cursor/hooks.json` | `preToolUse` | `hooks/ledger-guard-cursor.sh` |
+
+Any other harness that can run a command and read those two exit codes can use `ledger-guard.sh` by
+hand.
+
+**Cursor needs a second protocol, and this is the trap.** Its `preToolUse` is a *permission hook*:
+Cursor's docs say that for a permission hook, "invalid JSON or a response that doesn't match the
+hook's schema blocks the action". `ledger-guard.sh` prints **nothing** when it allows — and empty
+stdout is invalid JSON. Wiring it straight into Cursor would therefore have blocked **every** file
+write in a verified project: fail-closed on everything, the opposite of this guard's whole design, and
+invisible to any test that only checks that a deny denies.
+
+So Cursor gets `hooks/ledger-guard-cursor.sh`, installed only for a project whose targets include
+`.cursor`. It calls `yad hook ledger-guard --format cursor` through the shared script and guarantees a
+permission answer on stdout, whatever happens:
+
+| | stdout | exit |
+|---|---|---|
+| allow | `{"permission":"allow"}` | 0 |
+| deny | `{"permission":"deny","user_message":"<reason>","agent_message":"<reason>"}` | 0 |
+
+The field names are Cursor's documented permission-hook schema, all snake_case. Getting that wrong is
+quiet in the worst way: an off-schema response still blocks, so the write is refused and any test that
+checks "a deny denies" passes — while the text naming `yad gate open` is discarded and the agent is
+told only "no".
+
+The allow response is a fixed literal with nothing interpolated into it, because a malformed *allow*
+is a block. The deny response carries the reason, and if that field were ever rejected as off-schema
+the response is invalid — which blocks, which is what a deny wanted anyway. Both failure directions
+are safe, in opposite ways, on purpose. A deny exits **0**, not 2, because the JSON is the
+authoritative answer and exit 0 is what tells Cursor to read it; exit 2 blocks too but is documented
+as the code for "no JSON to read", so it would discard the reason — and naming the command that owns
+the transition is the entire point of speaking at edit time. The reason also goes to stderr, where
+Cursor logs it.
+
+The wrapper takes **no arguments**, and every fail-open branch of the shared script (no `yad` on
+PATH, an install it cannot resolve) is converted into an explicit `allow` answer rather than the
+empty stdout that would block. **Exit 2 is converted into a deny**, not an allow: `ledger-guard.sh`
+resolves `yad` from the Product's own `node_modules/yadflow` before `PATH`, so a project pinned to a
+yadflow older than `--format` answers in the exit protocol — exit 2 with empty stdout — and treating
+that as "no verdict" would turn a real refusal into a permitted write.
+
+The two commands are spelled differently on purpose. Claude Code runs the string through a shell, so
+its entry uses `$CLAUDE_PROJECT_DIR` and is quoted against a project path containing a space. Cursor
+documents that a project hook runs **from the project root** but not whether the command goes through
+a shell — so its entry is a relative path with no variable and no quotes, the one spelling that works
+either way. Every failure mode here is silent and fails open, which would leave `yad doctor`
+truthfully reporting an entry that never refuses anything.
+
+Cursor does not document the field names inside `tool_input`, so `payloadPaths` reads any key *named*
+like a path (`file_path`, `target_file`, `filePath`, `paths`) rather than guessing a vendor spelling.
+It matches the key and never the value: scanning values for something shaped like a ledger path would
+refuse an ordinary edit to a document that merely quotes one, and a false deny is worse than a miss in
+a guard that fails open by design.
+
+Cursor's wiring follows Cursor's published protocol and has not yet been exercised against a live
+Cursor session.
+
+**Layering.** `hooks/ledger-guard.sh` is only the adapter: it locates `yad` (`$YAD_BIN` → the Product's
 `node_modules/yadflow` → `PATH` → `npx --no-install`) and passes the payload to `yad hook
 ledger-guard`, which holds the decision. So the wiring never hard-codes an install path, and the
 logic is unit-tested (`cli/hook.mjs`, `cli/test.mjs`) instead of living in bash.
@@ -445,7 +669,7 @@ logic is unit-tested (`cli/hook.mjs`, `cli/test.mjs`) instead of living in bash.
 - **The seed carve-out reads the base ref, not the working tree** (#162): the epics whose
   `state.json` the base carries are listed once with `ls-tree`, and an epic absent from that list is
   a creation. Never a `<rev>:<path>` probe — that spec resolves from the repository top level and
-  `-C` does not re-anchor it, so a hub in a subdirectory of its repo would miss every time and the
+  `-C` does not re-anchor it, so a Product in a subdirectory of its repo would miss every time and the
   guard would allow everything, silently.
 - **The base is an `origin/` ref** — `origin/<default_branch>`, then the remote's published default,
   then `origin/main`, the gate's own order. Never a bare local branch: `git fetch` does not
@@ -458,7 +682,7 @@ logic is unit-tested (`cli/hook.mjs`, `cli/test.mjs`) instead of living in bash.
   bridge the ledger is locally owned, the hand-edit the authoring skills describe is correct, and
   nothing is wired or blocked.
 
-**It fails OPEN, and that asymmetry is the design.** No `yad` on PATH, no hub above the edited path,
+**It fails OPEN, and that asymmetry is the design.** No `yad` on PATH, no Product above the edited path,
 an unreadable `hub.json`, an unparseable payload, a `yad` that errors — every one of them ALLOWS,
 with a note on stderr. A local guardrail that failed closed would brick an agent's ability to edit
 anything the moment an install went sideways. The CI gate fails **closed** and is what actually
@@ -468,19 +692,19 @@ protects the ledger; this only shortens the feedback loop. `YAD_HOOK_DISABLE=1`
 
 - A `Bash` tool call (`sed -i epics/…`) is not intercepted; matching it would mean parsing shell for
   write intent.
-- The hook arms sessions **rooted at the hub**. A harness loads hooks from its own project root, so a
-  session opened at the *workspace* (`project/`, with the hub at `project/product/`) never reads the
-  hub's `.claude/settings.json` and the guard does not fire there — even though the decision itself
-  resolves the hub correctly from any path. In that layout, open the session at the hub, or copy the
-  entry into the workspace's own settings (the command's `$CLAUDE_PROJECT_DIR` would then need the
-  hub-relative path).
+- The hook arms sessions **rooted at the Product**. A harness loads hooks from its own project root, so a
+  session opened at the *workspace* (`project/`, with the Product at `project/product/`) never reads the
+  Product's `.claude/settings.json` and the guard does not fire there — even though the decision itself
+  resolves the Product correctly from any path. In that layout, open the session at the Product, or copy the
+  entry into the workspace's own settings (the command's `$CLAUDE_PROJECT_DIR` would then need
+  the Product-relative path).
 
-**Wiring** (installed by `yad setup` / `yad check --fix`, bridge hubs only):
+**Wiring** (installed by `yad setup` / `yad check --fix`, verified Products only):
 
 | Path | Owner |
 |---|---|
-| `<hub>/hooks/ledger-guard.sh` | fully managed — drift-checked and recorded in `.sdlc/managed.json` like any gate script |
-| `<hub>/.claude/settings.json` | **one entry**, merged additively into `hooks.PreToolUse`. See below. |
+| `<product>/hooks/ledger-guard.sh` | fully managed — drift-checked and recorded in `.sdlc/managed.json` like any gate script |
+| `<product>/.claude/settings.json` | **one entry**, merged additively into `hooks.PreToolUse`. See below. |
 
 The settings file is the team's, so the rules around that one entry are deliberately conservative:
 
@@ -502,10 +726,11 @@ The settings file is the team's, so the rules around that one entry are delibera
 - **Both halves land together.** The script and the entry ride `yad update` as one: applying the
   entry without the script it points at would fire a missing command on every file edit.
 
-`.claude` is the only IDE target wired: it is the only one with a defined hook protocol. Other
-targets get the script, and the contract above is what they would wire by hand.
+`.claude` and `.cursor` are the only IDE targets wired (`.cursor` through its own wrapper, above): they
+are the only ones with a hook protocol yadflow has read. Other targets get the script, and the contract
+above is what they would wire by hand.
 
-`yad doctor` reports the guard on a verified hub, and distinguishes the three states that matter — it
+`yad doctor` reports the guard on a verified Product, and distinguishes the three states that matter — it
 reads the same persisted `ideTargets` the wiring reads, so every gap it names is one the command it
 names can actually close: