yadflow 4.0.0-next.3 → 4.0.0

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

@@ -22,7 +22,7 @@ trigger is a parameter, not a hardcoded human.
 - Operate on one epic: `{project-root}/epics/EP-<slug>/`. The Product level is the exception:
   `EP-foundation` lives at `{project-root}/foundation/` (its `.sdlc/` and `reviews/` are there).
 - State files: `.sdlc/state.json`, `.sdlc/approvals.json`, `.sdlc/comments.json`, and (when the verified ledger is
-  used) `.sdlc/hub-prs.json`. Review records: `reviews/`.
+  used) `.sdlc/product-prs.json` (written together with its older name `hub-prs.json`). Review records: `reviews/`.
 - The artifact base name drops the extension (`epic.md` → `epic`; story `stories/...S01.md` → `stories-S01`).
 
 ## Inputs
@@ -32,7 +32,7 @@ trigger is a parameter, not a hardcoded human.
   `comment` / `approve` / `advance` are the `yad gate comment|approve|advance` commands (E112).
 - For `comment` / `approve`: the reviewer's platform login (or the name they give, when there is no
   platform). No role and no domain. Ask if not provided.
-- `sync` needs no reviewer input — it reads the platform PR/MR review state (via `yad-hub-bridge`).
+- `sync` needs no reviewer input — it reads the platform PR/MR review state (via `yad-product-bridge`).
 
 ## On Activation
 
@@ -54,9 +54,8 @@ roles — there are no roles, and yadflow keeps no list of people:
   (`short`); never block on it. Why: the count of people errs high in the normal case. A commit is
   counted by its git name, an approval by its platform login, and yadflow never joins the two without
   exact evidence — so a two-person team can read as four. At four the cap lowers nothing, and an enforced
-  contract gate would ask three approvals of a team with one person who is not the author. A later yadflow
-  change turns the capped count on together with `yad gate lower --reason`, the way out, once the count
-  is accurate.
+  contract gate would ask three approvals of a team with one person who is not the author. Enforcing the
+  capped count is parked (roadmap E108) until the count is accurate.
 - **Relay a warning line.** Under a team gate that has not passed, `yad gate status` and `yad gate sync`
   print `! may not be met: …` (today's one required approval may have nobody but the author to give
   it) or `! if the risk step were enforced: …` (a what-if about the extra approvals) when the count of
@@ -66,7 +65,7 @@ roles — there are no roles, and yadflow keeps no list of people:
   one person may work on the Product (E74). Relay it as a suggestion to run `yad mode team`; never switch
   the mode yourself, and never read it as a fault.
 - **When the people cannot be counted** (`active: null` — for example Product CI, which checks out only
-  the hub, so the connected repos are not on disk): **no cap is computed or shown**, and the base holds as
+  the Product, so the connected repos are not on disk): **no cap is computed or shown**, and the base holds as
   always. `yad gate status` and `yad gate sync` print the arithmetic — read it from there rather than
   recomputing it.
 - **Touched domains** only name and label the review; they add no approvals. For a step with a risk
@@ -78,7 +77,7 @@ and nothing else.
 
 ### Step 2 — Dispatch on `action`
 
-> **Check the mode first — in verified mode you write nothing to the ledger.** Read `.sdlc/hub.json`:
+> **Check the mode first — in verified mode you write nothing to the ledger.** Read `.sdlc/product.json` (`.sdlc/hub.json` on an older Product that has only that name):
 > **verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present. Under the verified ledger
 > the ledger is CI-owned — `ledger-guard` rejects any non-bot commit touching
 > `epics/*/.sdlc/{state,approvals,comments,product-prs,hub-prs}.json` or `epics/*/reviews/*.md` (and the
@@ -117,14 +116,14 @@ transition at merge.
 
 Do not advance.
 
-If `.sdlc/hub.json` has a non-null `platform` and `gh`/`glab` is authenticated, **`yad gate open` also
-opens the review PR/MR on the Product** (the recipe is `yad-hub-bridge action: open`; do not open a
+If `.sdlc/product.json` (`.sdlc/hub.json` on an older Product) has a non-null `platform` and `gh`/`glab` is authenticated, **`yad gate open` also
+opens the review PR/MR on the Product** (the recipe is `yad-product-bridge action: open`; do not open a
 second one), and you report the URL. This holds for a verified ledger and for a local one. The PR
 requests **no reviewers**; the command prints
 `no reviewers were requested — ask them on the PR itself`, so tell the author to ask people on the PR.
-The PR is recorded in `epics/<epic>/.sdlc/hub-prs.json` (`{step, artifact, platform, number, url, branch, lastSyncedAt}`):
+The PR is recorded in `epics/<epic>/.sdlc/product-prs.json` and `hub-prs.json`, same bytes (`{step, artifact, platform, number, url, branch, lastSyncedAt}`):
 **by CI at merge** in verified mode (`ledger: "verified"`, or, before `yad migrate`, `bridge_enabled: true` /
-legacy `bridge: true` — `.sdlc/hub.json` is the only source the CLI reads, see `isVerifiedLedger` in
+legacy `bridge: true` — `.sdlc/product.json` (else `.sdlc/hub.json`) is the only source the CLI reads, see `isVerifiedLedger` in
 `cli/manifest.mjs`), and by `yad gate open` itself on a local ledger. Never write it by hand (see `sync`
 below). With no platform, or when the PR cannot be opened on a local ledger, the step is still
 `in_review` locally — no error. (In verified mode a failed open writes nothing; open the PR by hand and
@@ -173,7 +172,7 @@ replaced. This is the **no-platform** path (E112): with a platform the approvals
 command refuses and names `yad gate sync`; on a verified ledger CI writes them at merge.
 `engagement` records whether the approval came through the [Review Companion](../yad-review-companion/SKILL.md)
 (a real trailer/cards/chat session = `verified`) or as a bare click (`none`). It is soft by default
-(both count; a bare approve draws a friendly nudge) and only gates when `hub.review.requireEngagement`
+(both count; a bare approve draws a friendly nudge) and only gates when `review.requireEngagement` (Product settings)
 is on — see `references/gating.md`. The signal is gameable by design ("visible, not impossible").
 Then write/refresh `reviews/<artifact-base>--<YYYY-MM-DD>--approved.md` as a **named record** — the command
 writes the ledger only, never this file, so rewrite it after every `yad gate approve`. It has three
@@ -200,18 +199,18 @@ The command prints the verdict (Step 3) itself. Recording an approval does NOT a
 separate, explicit act (`advance`), the way approving a PR never merges it.
 
 **`sync`** — (the platform bridge input path) Pull the Product review PR/MR's review state into the ledger,
-then re-evaluate the rule (Step 3). Read the PR for this step from `.sdlc/hub-prs.json` and use
-`yad-hub-bridge`'s read recipes (`../yad-hub-bridge/references/bridge.md`) to fetch reviews + comments
+then re-evaluate the rule (Step 3). Read the PR for this step from `.sdlc/product-prs.json` (`hub-prs.json` when that is absent) and use
+`yad-product-bridge`'s read recipes (`../yad-product-bridge/references/bridge.md`) to fetch reviews + comments
 via the local user's `gh`/`glab`. For each:
 - the platform `login` is the name written — `approver` / `commenter` is the login itself. There is no
-  lookup and no role (see `../yad-hub-bridge/references/login-roster.md`);
+  lookup and no role (see `../yad-product-bridge/references/login-roster.md`);
 - an `APPROVED` review / MR approval → append an `approved` record to `approvals.json` tagged
   `"source": "bridge"`; a `CHANGES_REQUESTED` review or an unresolved thread → write to
   `reviews/<artifact-base>--<YYYY-MM-DD>--comments.md` + `comments.json` (never an approval). A resolved
   thread, and a companion comment marked `<!-- yad:noblock -->`, is not written.
 **Idempotent:** upsert bridge approvals by `(step, approver)` — one record per person. An older record
 that still carries `role`/`domain` and names a person by their old roster name is recognised as
-`../yad-hub-bridge/references/login-roster.md` → "Older records" describes, and replaced by one
+`../yad-product-bridge/references/login-roster.md` → "Older records" describes, and replaced by one
 login-named record that keeps its fingerprint. Every sync write (`yad gate sync`, `yad gate ci`) also
 records the login on the older records the roster can place for certain, on every step (same reference → "Recording the login on older records").
 A bridge approval records the platform's evidence — `approvedAt`, and on GitHub `commit`, `url` and
@@ -223,7 +222,7 @@ it. **Manual approvals (no `source` tag) are never touched.** For the architectu
 fingerprint a bridge approval is bound to is the contract surface, so a re-lock makes every approval of
 the old surface stale: it stays on disk and no longer counts (re-lock invalidates platform approvals
 too). Then refresh the `approved.md`
-record, set the PR ledger's `lastSyncedAt`, and **re-evaluate Step 3**. **Never hand-write either PR-ledger file.** It lives under two names while the rename settles — `product-prs.json` and `hub-prs.json` — and the engine writes both together. Writing one leaves the pair disagreeing, and `yad doctor` will report it. Use `yad gate`, which keeps them in step.  Under the PR-driven CLI (`yad
+record, set the PR ledger's `lastSyncedAt`, and **re-evaluate Step 3**. **Never hand-write either PR-ledger file.** It lives under two names until v5 — `product-prs.json` (read first) and `hub-prs.json` — and the engine writes both together. Writing one leaves the pair disagreeing, and then every yad command refuses (YAD-STATE-008) until `yad migrate --apply` settles it. Use `yad gate`, which keeps them in step.  Under the PR-driven CLI (`yad
 gate sync`), `sync` advances the step when Step 3 passes on a **merged**, fully-resolved, approved PR
 (the merge is the human act); otherwise it records state and holds the step `in_review`.
 
@@ -239,7 +238,7 @@ The step may advance **iff ALL hold**:
    the base holds. Report the shortfall in the record; do not hold the step on it.
    This matches `gatePredicate`, which returns `rule: "count"`, the count as `gateRule`/`have`/`short`,
    `active`, and `cap` (null when `active` is null), and never puts the risk step in `missing`.
-   `active: null` means no source could be read, never "nobody". With `hub.review.requireEngagement`
+   `active: null` means no source could be read, never "nobody". With `review.requireEngagement` (Product settings)
    on, only `verified` approvals count.
 2. The artifact has not changed since the latest approval round (no newer authored edit than the
    newest `approved` record). If it changed, approvals are stale → return to `comment`. For the
@@ -296,7 +295,7 @@ records this skill describes. The skill's
 job is the human half: presenting the artifact, helping the owner address comments, and narrating the
 gate. Local `yad gate sync` is advisory in verified mode (reads the platform, prints status, writes
 nothing); a human must never commit gate-state files (the `ledger-guard` check rejects it, and the
-`hooks/ledger-guard.sh` harness hook refuses an agent the edit up front, naming `yad gate open`
+`hooks/ledger-guard.mjs` harness hook refuses an agent the edit up front, naming `yad gate open`
 instead — see `yad-checks`). The single
 exception is an epic's **seed** — no CI path can create a ledger, so a brand-new epic's `.sdlc/` rides
 its **first** review PR/MR, cut from the authoring branch (creation, not mutation, #162).
@@ -312,7 +311,7 @@ PR/MR are recorded and bound to the new content. `yad gate status` then shows th
 approvals are live against what is in the file today, and how many were revoked — instead of a `done`
 step whose approvals all belong to the version before the edit.
 
-The flow is **merge-driven** (wired by `yad-hub-bridge` `wire`): during review CI writes nothing — the
+The flow is **merge-driven** (wired by `yad-product-bridge` `wire`): during review CI writes nothing — the
 platform PR/MR is the source of truth (native approvals + threads), and CI never touches the review
 branch (so an in-flight approval is never dismissed and required checks never strand). On the human
 **merge** CI re-reads approvals, advances the step, and flips the artifact `status:` on the **default
@@ -323,8 +322,8 @@ write path.
 ### Hard rules (build plan §1, §5)
 - **The merge click is the human approval act.** A Shape step advances only when a human merges the
   approved, fully-resolved review PR — or, on a Product with no platform, when a person runs
-  `yad gate advance` — there is no machine-driven advance. A step `locked: true` may not
-  be switched to `advance: auto`; refuse such a request.
+  `yad gate advance` — there is no machine-driven advance. A review gate is never `advance: auto`
+  (`yad dial` refuses it); refuse such a request.
 - **Approvals are revoked when the reviewed artifact changes.** `sync` re-hashes the artifact (the locked
   contract surface for architecture; every other file without its frontmatter `status:` line, which the
   gate and Build rewrite after review) and drops any approval bound to a stale hash, so a reviewer must
@@ -338,4 +337,4 @@ write path.
 
 ## Reference
 - Gating details and worked example: `references/gating.md`.
-- The platform PR/MR bridge (`open`/`sync` mechanics, read recipes, login attribution): `../yad-hub-bridge/SKILL.md`.
+- The platform PR/MR bridge (`open`/`sync` mechanics, read recipes, login attribution): `../yad-product-bridge/SKILL.md`.

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

@@ -55,8 +55,8 @@ the risk step.
 counted by its git name, an approval by its platform login, and yadflow never joins the two without
 exact evidence. So an ordinary two-person team can read as **four**. At four the cap lowers nothing,
 and an enforced contract gate would ask three approvals of a team with one person who is not the author
-— a gate it could never pass. A later yadflow change turns the capped count on together with
-`yad gate lower --reason`, the way out of a gate that cannot be met, once the count is accurate.
+— a gate it could never pass. Enforcing the capped count, with a way out for a gate that cannot be
+met, is roadmap row E108, which is parked. Until then the count is advice only.
 
 **When a gate may not pass (E73).** `yad gate status` and `yad gate sync` print a warning line under a
 team review gate that has not passed yet, when the count of people suggests the gate may not pass. It is a
@@ -116,7 +116,7 @@ people, because the connected repos are not on disk there.
 
 **When the people cannot be counted** (`active: null` — a source could not be read), **no cap is
 computed or shown**, and the base holds as always. The engine never guesses a small number from an
-unknown. Product CI is usually this case: it checks out only the hub, so on a Product with connected
+unknown. Product CI is usually this case: it checks out only the Product, so on a Product with connected
 repos the repos are not on disk.
 
 **Every cap is recorded.** When a **team** gate passes on its counted approvals while the cap lowered
@@ -132,7 +132,7 @@ Why count people: the rule names no person, no role and no step. A stored list o
 stale; repository access decides who can approve.
 
 Four surfaces print the count with its cap: `yad gate sync`, `yad gate status`, the generated
-review-PR body and `yad open-pr`. (`checks/risk-route.sh` and `checks/hub-route.sh` print the count
+review-PR body and `yad open-pr`. (`checks/risk-route.sh` and `checks/product-route.sh` print the count
 without the cap — they cannot count people.) `yad gate sync` and `yad gate status` share one suffix; the review-PR body and `yad
 open-pr` word the cap their own way (below). The shared suffix appears only when the step has a risk
 step. It names the cap only when the cap lowered the ask, and always ends by saying what holds:
@@ -177,7 +177,7 @@ not be counted, nothing is suggested: `yad mode` and `yad doctor` (a warning) sa
 `verified` when it was recorded through the companion (a real trailer/cards/chat session), `none` for a
 bare UI click. By **default (soft)** both count: a bare approve still passes the gate but is recorded
 `none` and draws a friendly public @-mention nudge, so review *quality* is visible without blocking
-anyone. When `hub.review.requireEngagement: true`, only `verified` approvals are counted toward the
+anyone. When `review.requireEngagement: true` in the Product settings, only `verified` approvals are counted toward the
 approvers above; when that leaves the gate short, it adds a line saying how many approvals did not count (a determined faker
 can still run an empty session — the signal is **gameable by design**; it raises the cost of a
 rubber-stamp and makes laziness visible, it does not prove a human read the artifact). Philosophy:
@@ -249,7 +249,7 @@ not "resolve to pass" — it ignores them). A reviewer's *genuine* concern is po
 marker and blocks normally, exactly as a `CHANGES_REQUESTED` or any unresolved human thread does.
 
 ## Platform-backed input (the verified ledger)
-When the Product has a platform (`.sdlc/hub.json`), reviewers can approve/comment
+When the Product has a platform (`.sdlc/product.json`), reviewers can approve/comment
 on a real PR/MR instead — and only there: with a platform, `yad gate approve` / `comment` / `advance`
 refuse. The sync reads that platform
 state with the local user's own `gh`/`glab` and writes the **same**
@@ -262,26 +262,26 @@ unchanged**: it counts distinct approvers regardless of how they were recorded.
 - On PR/MR open the assignee is whoever opens it: `@me` on GitHub, and the login `glab` reports on GitLab.
   **No reviewers are requested** — the command prints `no reviewers were requested — ask them on the
   PR itself`. `domain:<repo>` labels for the touched domains are still applied. See
-  `../yad-hub-bridge/references/login-roster.md`.
+  `../yad-product-bridge/references/login-roster.md`.
 - `sync` is idempotent (upsert by `(step, approver)`, one record per person; comment records by
   `(step, commenter, round)`, an unchanged round rewritten in place) and never touches **manual** approvals. An older bridge record that carries `role`/`domain` is
-  recognised as `../yad-hub-bridge/references/login-roster.md` → "Older records" describes, and replaced
+  recognised as `../yad-product-bridge/references/login-roster.md` → "Older records" describes, and replaced
   by one login-named record that keeps its fingerprint. Every sync write (`yad gate sync`, `yad gate ci`)
   also records the login on the older records the roster can place for certain; only those it cannot
   place still need the roster on a later sync. A bridge approval records the
   platform's evidence (`approvedAt`, and on GitHub `commit`, `url`, `reviewId`) — for the record only. A revoked approval is superseded **while the step is open**; once
   the step is `done` its approvals are kept as the record of why it passed, and a re-sync only re-binds
-  new ones (see `../yad-hub-bridge/references/bridge.md` → "Idempotent re-sync").
+  new ones (see `../yad-product-bridge/references/bridge.md` → "Idempotent re-sync").
 - The architecture+contract staleness rule applies to bridge approvals too: a re-lock changes the
   surface fingerprint, so bridge approvals of the old surface stop counting (they stay on disk as revoked).
-- No platform / no CLI → the gate runs local with no error. Detail: `../yad-hub-bridge/references/bridge.md`.
+- No platform / no CLI → the gate runs local with no error. Detail: `../yad-product-bridge/references/bridge.md`.
 
 ## Why this shape
 - One approver who is not the author keeps review load low on a small team (design priority 2) while
   still requiring a second pair of eyes (priority 1, code quality / production safety).
 - The risk step asks for more people only where a change can break a shared surface
-  (contract/auth/payments). It is advisory for now: the capacity cap (E72) is reported. A later change will
-  enforce it together with `yad gate lower --reason`, so that a gate asking for more people than the team
-  has will always have a way out. Until then E73 only warns when a gate may not pass.
+  (contract/auth/payments). It is advisory for now: the capacity cap (E72) is reported. Enforcing it, with a way
+  out for a gate that asks for more people than the team has, is roadmap row E108, which is parked. Until
+  then E73 only warns when a gate may not pass.
 - No stored list of people: it goes stale, and repository access already decides who can approve.
 - Everything is a file, so a future service can drive the same gate by writing the same records.

package/skills/yad-run/SKILL.md

@@ -117,9 +117,9 @@ Walk the steps for `repo` starting at `from`/`currentStep`. For each step:
 
 **Commit the machine-written state.** After each iteration's writes (the trust-log shard in 2 and the
 build-state change in 4), run `yad checkpoint --push` from `{project-root}`. It commits *only* the
-`trust-log/` shards + `build-state/<story>.json` (never a Shape gate file) as one `chore(hub): …`
+`trust-log/` shards + `build-state/<story>.json` (never a Shape gate file) as one `chore(product): …`
 audit-trail commit, and only ever on the default branch. It is a safe no-op when nothing changed, so
-call it every iteration — teammates don't review these machine writes, but CI and `yad status` on
+call it every iteration — teammates don't review these machine writes, but CI and the `yad-status` skill on
 other machines must see current trust evidence. Never run it off the default branch (it will refuse):
 an unpushed or branch-stranded trust log leaves the run record `yad dial` shows out of date.
 

package/skills/yad-run/references/run-loop.md

@@ -83,12 +83,12 @@ also the `build-log/` shards at engineer-review) — the shard dirs are what che
 way `git gc` folds loose objects later (`yad tidy up` folds finished shards into the folded
 `trust-log.json` / `build-log.json`) — plus any story `status:` flip (→ in-build/shipped) once that
 story has a build-log ship (#112) — as one
-`chore(hub): sync Build state — <epic>/<story> by @<login> [skip ci]`
+`chore(product): sync Build state — <epic>/<story> by @<login> [skip ci]`
 audit-trail commit (`@<login>` when the platform login is known, else the git `user.name`, else `unknown`), on the default branch only,
 staging *only* those files by an explicit allowlist (never a Shape gate file — so `ledger-guard`
 never trips). It is idempotent (a no-op when nothing changed), so calling it after every transition —
 including a halt — is safe and keeps the shared trust evidence current for CI, teammates, and
-`yad status` on other machines. It refuses to run off the default branch (an unsigned `[skip ci]`
+the `yad-status` skill on other machines. It refuses to run off the default branch (an unsigned `[skip ci]`
 commit inside a future PR range would fail `verified-commits` and strand the PR).
 
 ## Effective dial (the kill switch and gates always win)

package/skills/yad-spec/SKILL.md

@@ -95,7 +95,8 @@ to read. See `references/spec-handoff.md` for the exact file map and per-file de
 ### Step 6 — Write link.md back to the story
 Write `demo-repos/<repo>/specs/<story>/link.md` (template in `references/spec-handoff.md`) with
 frontmatter linking the spec back to the product repo: `story`, `epic`, `repo`, `feature-id`,
-`product-repo` (path), `contract-lock` (the hash **copied** from `contract-lock.json`, NOT recomputed
+`product-repo` (path — when the code repo has `.sdlc/product-link.json`, write `../../<its path>`, the
+place CI checks the Product out; the gates read that record first anyway), `contract-lock` (the hash **copied** from `contract-lock.json`, NOT recomputed
 in the code repo — or the literal `none` on a short-lane epic, which has no lock; never a made-up or
 empty hash, which the CI gate reads as a broken lock and fails), `speckit`
 (`installed | not-installed`), `generated` (date). This `link.md` plus the

package/skills/yad-spec/references/spec-handoff.md

@@ -94,19 +94,28 @@ The contract surface above is **referenced, not re-defined**. Any change to the
 back to the architecture gate in the product repo — it is never widened from this code repo.
 ```
 
+`epic` must be the story ID's prefix (`EP-<slug>-S0N` → `EP-<slug>`); lineage-check, epic-open and
+reconcile-debt-check FAIL on any other value (E118).
+
 `product-repo` is the one field CI resolves on disk (contract-check, lineage-check, epic-open,
 reconcile-debt all read it). Every gate resolves it the SAME way: an **absolute** path is used as-is; a
-**relative** path is joined to this `link.md`'s own directory, `specs/<story>/` — `../../` climbs out
-of the story dir and out of `specs/` to the code-repo root, so a Product checked out beside the code repo
+**relative** path is joined to this `link.md`'s own directory, `specs/<story>/` — `../../` climbs out of
+the story dir and out of `specs/` to the code-repo root, so a Product checked out beside the code repo
 is `../../../<product-dir>`. A relative value that only resolves from the **repo root** still works too
-(what contract-check historically did), so older `link.md` files keep gating. Write it as an
-**unquoted scalar** — `"..."` or `'...'` is taken literally, and a leading `~`/`$VAR` is never
-expanded. An unreachable path degrades the Product-reading gates to a PASS-with-note rather than failing
-them, and each one now says so in its output. **Reachable-but-lockless is a different case and does
-NOT degrade:** when the Product resolves and `epics/<epic>/.sdlc/` is there with no
-`contract-lock.json` in it, a claimed `Contract-Change: yes` FAILS, because nothing exists for the
-claim to be true of. That is the ordinary state of a short-lane epic, of a stub, and of a classic epic
-that has not reached its architecture gate yet.
+(what contract-check historically did), so older `link.md` files keep gating. Write it as an **unquoted
+scalar** — `"..."` or `'...'` is taken literally, and a leading `~`/`$VAR` is never expanded. An
+unreachable path degrades the Product-reading gates to a PASS-with-note rather than failing them, and
+each one now says so in its output. **CI reads `product-repo` from `link.md` as it stands on the base
+branch** once one is merged (E117): a PR that changes it is read by the old value, and the new one
+counts after the merge. **A merged `.sdlc/product-link.json` in the code repo comes before all of it
+(E120):** its `path` (from the repo root, where CI checks the Product out) is what the gates read, and
+`link.md`'s `product-repo` is only a fallback for a repo without one — so write `../../<that path>` here
+when the record exists. A Product folder that the code repo itself tracks (a monorepo) is read as it
+stands on the base commit, so a re-lock must merge before the slice change that pins it.
+**Reachable-but-lockless is a different case and does NOT degrade:** when the Product resolves and
+`epics/<epic>/.sdlc/` is there with no `contract-lock.json` in it, a claimed `Contract-Change: yes`
+FAILS, because nothing exists for the claim to be true of. That is the ordinary state of a short-lane
+epic, of a stub, and of a classic epic that has not reached its architecture gate yet.
 
 ## Do not re-invent the contract
 

package/skills/yad-stories/SKILL.md

@@ -113,7 +113,7 @@ As a <role>, I want <capability>, so that <outcome>.
 `repos` is the field the later build phase reads to know where to scaffold specs — set it precisely.
 
 ### Step 6 — Advance the authoring step (NOT the gate)
-**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/product.json` (`.sdlc/hub.json` on an older Product that has only that name):
 **verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present.
 
 **verified mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
@@ -145,7 +145,7 @@ reviewers — the team asks them on the review PR itself. When this gate
 passes the epic becomes **`ready-for-build`** — Build can start **and** the parallel
 **`test-cases`** track opens for the tester (`yad-test-cases`); the two run at the same time. **Never record
 approval here.** Shape steps do not auto-advance. When the Product has a platform, the gate opens a review
-PR on the Product (via `yad-hub-bridge`, with a `domain:<repo>` label per touched repo) and
+PR on the Product (via `yad-product-bridge`, with a `domain:<repo>` label per touched repo) and
 `yad-review-gate action: sync` pulls platform approvals/comments into the ledger; otherwise the review
 is recorded local.
 

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

@@ -35,8 +35,21 @@ tree (branch + fast-forward). It writes **nothing** back to the registry.
 Run `yad repo sync [<repo>]`. For each target repo it performs, in order:
 
 ### Step 1 — Locate and validate the repo
-Resolve the local path from the registry. If the path is not a git repo (no readable `HEAD`), warn and
-skip — there is nothing to switch.
+Resolve the local path from the registry. The registry is **shared content** — anyone who can push to
+the Product wrote it — so the path is judged before any git runs (E81), the same way `yad join` and
+`yad repo clone` judge it. The repo is **skipped with the reason** when:
+- the path is outside the workspace (the Product folder's parent), or runs through a `.git` folder;
+- nothing is there yet — **not cloned on this machine**: run `yad repo clone` to clone it;
+- a folder is there but is not a checkout (a folder the Product commits could be shaped like a bare
+  git repo, and git run inside it would read its `config`, which can run a command). A folder inside a
+  checkout with no `.git` of its own (`apps/web` in a monorepo) is not refused (unless a link inside a
+  repo's tree or a folder holding an entry named `HEAD` is on its way — git can take such a folder for
+  a bare repo), but sync still skips it: switching its branch would switch the whole checkout, so sync
+  that checkout instead;
+- a folder on the way, **inside a repo's tree**, is a link — the Product's `evil -> ../../..`. A link of
+  your own directly in the workspace folder (`ws/backend -> /src/backend`) is followed.
+
+If the path is a checkout but `HEAD` is unreadable, warn and skip — there is nothing to switch.
 
 ### Step 2 — Skip a dirty working tree (never overwrite local work)
 If `git status --porcelain` is non-empty, the repo has uncommitted changes: **skip it and warn**
@@ -45,6 +58,9 @@ preserving local work is a hard rule.
 
 ### Step 3 — Determine the default branch
 Use the registry `default_branch`. If absent, fall back to the remote's `origin/HEAD`, else `main`.
+A recorded name must be a valid `refs/heads/<name>` (`git check-ref-format`) and must not start with
+`-` or `+`: the name is handed to `git fetch`, where `--upload-pack=<command>` would run a command.
+Any other name skips the repo with the reason (fix it in `.sdlc/repos.json`).
 
 ### Step 4 — Fetch the latest
 If the repo has an `origin` remote: `git fetch origin <default_branch> --prune`. A local-only repo
@@ -65,7 +81,7 @@ so any repo whose `HEAD` now differs from its registry `syncedHead` has a **stal
 the command ends by pointing the human at `yad repo refresh` to repack (that is a separate human
 decision; this skill never repacks or writes the registry). After the repack + AI code-map
 regeneration, `yad repo refresh --push` publishes the refreshed code-maps + registry to the Product's
-default branch as a `chore(hub): sync code-context … [skip ci]` audit commit.
+default branch as a `chore(product): sync code-context … [skip ci]` audit commit.
 
 ## Hard rules
 

package/skills/yad-test-cases/SKILL.md

@@ -164,7 +164,7 @@ Keep the `## Automation (<tool>)` section of `test-cases.md` in step with this f
 degraded (`testing: none`), do **not** write `test-links.json`.
 
 ### Step 5 — Advance the authoring step (NOT the gate)
-**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/product.json` (`.sdlc/hub.json` on an older Product that has only that name):
 **verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present.
 
 **verified mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
@@ -195,7 +195,7 @@ Report: the path to `test-cases.md`, the connected testing tool and what it prod
 Build may already be underway in parallel, and that the next action is **review** via
 `yad-review-gate` (base rule: 1 distinct approver, who should not be the author). **Never record approval here.** Shape steps do not
 auto-advance. When the Product has a platform, the gate opens a review
-PR on the Product (via `yad-hub-bridge`) and `yad-review-gate action: sync` pulls platform approvals/comments
+PR on the Product (via `yad-product-bridge`) and `yad-review-gate action: sync` pulls platform approvals/comments
 into the ledger; otherwise the review is recorded local.
 
 ## Reference

package/skills/yad-ui/SKILL.md

@@ -184,7 +184,7 @@ Keep the `## Design (<tool>)` section of `ui-design.md` in step with this file.
 (`design: none`), do **not** write `design-links.json`.
 
 ### Step 5 — Advance the authoring step (NOT the gate)
-**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/product.json` (`.sdlc/hub.json` on an older Product that has only that name):
 **verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present.
 
 **verified mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
@@ -216,7 +216,7 @@ Report: the paths to `ui-design.md` and `DESIGN.md`, whether Impeccable was used
 tool and what it produced (e.g. "Figma — 4 screens generated", the file URL + `design-links.json` path,
 or "no design tool — markdown-only"), and that the next action is **review** via `yad-review-gate` (base
 rule: 1 distinct approver, who should not be the author). **Never record approval here.** Shape steps do not auto-advance. When the Product has a platform, the gate opens a review PR on the
-Product (via `yad-hub-bridge`) and `yad-review-gate action: sync` pulls platform approvals/comments into
+Product (via `yad-product-bridge`) and `yad-review-gate action: sync` pulls platform approvals/comments into
 the ledger; otherwise the review is recorded local.
 
 ## Reference

package/skills/yad-checks/templates/hooks/ledger-guard-cursor.sh

@@ -1,91 +0,0 @@
-#!/usr/bin/env bash
-# ledger-guard CURSOR ADAPTER — the same guard, answered in the protocol Cursor requires (E11).
-#
-# Cursor's `preToolUse` is a PERMISSION hook, and its docs are explicit: for a permission hook,
-# "invalid JSON or a response that doesn't match the hook's schema blocks the action". Empty stdout is
-# invalid JSON. The plain `ledger-guard.sh` prints nothing when it allows — so wiring it directly
-# would have blocked EVERY file write in a verified project, which is the exact opposite of this
-# guard's fail-open design.
-#
-# This wrapper guarantees one thing: a permission answer on stdout, always, whatever happens below.
-#
-#   allow   {"permission":"allow"}   exit 0
-#   deny    {"permission":"deny","user_message":"<reason>","agent_message":"<reason>"}   exit 0
-#
-# A deny exits 0 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" and would discard the
-# reason — and naming the command that owns the transition is the whole point of speaking at edit time.
-#
-# It takes NO arguments, deliberately. Cursor's `hooks.json` holds one command STRING and does not
-# document whether it is run through a shell, so a command with a flag in it might never be split into
-# program and argument — a command not found, silently, on every call.
-set -uo pipefail
-
-# `CDPATH=` is load-bearing, and the Cursor entry is what makes it so: that entry invokes the script
-# by a RELATIVE path, so `${BASH_SOURCE[0]}` is relative and `cd` consults $CDPATH before the current
-# directory. An exported CDPATH in a login profile — an ordinary thing to have, and inherited by the
-# harness — would resolve `hooks` to some other tree entirely, and the guard would fail open on every
-# write for as long as that profile lived.
-#
-# The loop resolves a symlinked SCRIPT, which `cd -P` does not: `-P` resolves the directory path, and
-# a script reached through a link in another directory would otherwise look for its sibling beside the
-# LINK and not find it. `readlink` without `-f` because `-f` is not portable to macOS.
-_src="${BASH_SOURCE[0]}"
-while [ -L "$_src" ]; do
-  _dir="$(CDPATH= cd -P -- "$(dirname -- "$_src")" && pwd)"
-  _src="$(readlink -- "$_src")"
-  case "$_src" in /*) ;; *) _src="$_dir/$_src" ;; esac
-done
-HOOK_DIR="$(CDPATH= cd -P -- "$(dirname -- "$_src")" && pwd)"
-ALLOW='{"permission":"allow"}'
-
-# Every failure below this line resolves to ALLOW, because this guard fails open by design and CI is
-# what fails closed. A wrapper that blocked when it could not reach `yad` would stop an agent editing
-# anything at all the moment an install went sideways.
-if [ ! -x "$HOOK_DIR/ledger-guard.sh" ]; then
-  echo "  • yad hook: $HOOK_DIR/ledger-guard.sh is missing or not executable — allowing (run \`yad check --fix\`)" >&2
-  echo "$ALLOW"
-  exit 0
-fi
-
-# stdout is CAPTURED (the JSON verdict), stderr is not (it flows through to Cursor's log). stdin is
-# inherited by the command substitution, so the tool-call payload still reaches the guard.
-raw="$("$HOOK_DIR/ledger-guard.sh" --format cursor)"
-rc=$?
-
-# THE VERDICT IS THE LAST NON-EMPTY LINE, not the whole of stdout, and it is recognised by containing
-# a `"permission"` key rather than by starting with one.
-#
-# Both halves of that matter. `yad`'s own top-level failure handler prints to STDOUT, so a usage error
-# or a crash banner can land in front of the JSON; a prefix test would then fail to recognise our own
-# deny and fall through to the allow below, turning a real refusal into a permitted write with nothing
-# on stderr to say so. And a containment test does not care what order the JSON's properties are in,
-# so the deny answer's shape on the other side of this language boundary is not silently load-bearing.
-verdict="$(printf '%s\n' "$raw" | awk 'NF { line = $0 } END { print line }')"
-
-# `ledger-guard.sh` has its own fail-open branches that exit 0 with EMPTY stdout — no `yad` on PATH,
-# an install it cannot resolve — and each one of those would otherwise reach Cursor as invalid JSON
-# and block the write.
-case "$verdict" in
-  *'"permission"'*) echo "$verdict"; exit 0 ;;
-esac
-
-# EXIT 2 IS A DENY, even with nothing on stdout — and this branch is reached in a real, ordinary case.
-# `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` parses the flag, ignores it, and answers in the
-# exit protocol: exit 2, empty stdout. Falling through to the generic allow below would turn a real
-# refusal into a permitted write, and print "exited 2 — allowing" while doing it.
-#
-# The message is a FIXED literal with nothing interpolated. The reason the older `yad` printed has
-# already gone to stderr, where Cursor logs it; escaping arbitrary multi-line text into JSON in bash
-# is exactly the sort of thing that produces an off-schema response, and there is no need to risk it.
-if [ "$rc" -eq 2 ]; then
-  echo '{"permission":"deny","user_message":"yad: this edit touches CI-owned gate state.","agent_message":"This edit touches CI-owned gate state, which CI is the sole writer of. Do not edit the ledger by hand: use `yad gate open` for the transition, and commit only the artifact. The installed yadflow is older than this hook, so the full reason is in the hook log rather than here — `yad doctor` will name the version gap."}'
-  exit 0
-fi
-
-if [ "$rc" -ne 0 ]; then
-  echo "  • yad hook: ledger-guard.sh exited $rc — allowing (run \`yad doctor\` to check the install)" >&2
-fi
-echo "$ALLOW"
-exit 0

package/skills/yad-checks/templates/hooks/ledger-guard.sh

@@ -1,100 +0,0 @@
-#!/usr/bin/env bash
-# ledger-guard HARNESS HOOK — the local half of the CI gate of the same name (#171).
-#
-# The gate ledger is CI-owned in verified mode: `checks/ledger-guard.sh` rejects any non-bot commit
-# that changes `epics/*/.sdlc/{state,approvals,comments,product-prs,hub-prs}.json` or `epics/*/reviews/*.md`,
-# and the same files for the Foundation in `foundation/.sdlc/` and `foundation/reviews/` (E75).
-# This hook says so at the moment an agent tries the edit, instead of twenty minutes later in a
-# failed pipeline, and names the command that owns the transition (`yad gate open`).
-#
-# This file is only the ADAPTER. It locates `yad` and hands the tool-call payload to
-# `yad hook ledger-guard`, which holds the decision — so the wiring never hard-codes an install path
-# and the logic stays testable. The contract it passes through:
-#
-#   stdin   the harness's tool-call payload as JSON (optional)
-#   exit 0  allow
-#   exit 2  deny, reason on stderr
-#
-# Wired by `yad check --fix` for every harness that can refuse a write BEFORE it lands:
-#   Claude Code  a `PreToolUse` hook in `.claude/settings.json`, pointing straight at THIS script
-#   Cursor       a `preToolUse` hook in `.cursor/hooks.json`, pointing at `ledger-guard-cursor.sh`
-#
-# DO NOT WIRE THIS SCRIPT INTO CURSOR DIRECTLY, and check the same thing before wiring it into any
-# other harness by hand. Cursor's `preToolUse` is a PERMISSION hook: it wants a JSON verdict on
-# stdout, and treats an empty or off-schema answer as a refusal. This script prints NOTHING when it
-# allows — so wired there directly it would block every file write in the project, which is the
-# opposite of the fail-open stance below. `ledger-guard-cursor.sh` exists to speak that protocol.
-#
-# A harness that reads the EXIT CODE can use this script as it stands. A hook that only fires AFTER
-# the write — Cursor's `afterFileEdit`, for one — is deliberately not used: it could report the edit
-# but never refuse it, and reporting is what the CI gate already does.
-#
-# The project root is resolved from this script's own location below, so it does not matter which
-# variable the harness sets ($CLAUDE_PROJECT_DIR, $CURSOR_PROJECT_DIR) or where it runs the command
-# from; those variables appear only in the wiring, to point at this file.
-#
-# FAIL-OPEN: if no `yad` can be found, this ALLOWS and says why on stderr. A guardrail that blocked
-# every edit the moment an install went sideways would be worse than the problem. The CI gate fails
-# CLOSED and is what actually protects the ledger.
-set -uo pipefail
-
-# The Product root is this script's grandparent — hooks/ledger-guard.sh — so the resolution below does
-# not depend on the harness's working directory.
-# `CDPATH=` is load-bearing, and the Cursor entry is what makes it so: that entry invokes the script
-# by a RELATIVE path, so `${BASH_SOURCE[0]}` is relative and `cd` consults $CDPATH before the current
-# directory. An exported CDPATH in a login profile — an ordinary thing to have, and inherited by the
-# harness — would resolve `hooks` to some other tree entirely, and the guard would fail open on every
-# write for as long as that profile lived.
-#
-# The loop resolves a symlinked SCRIPT, which `cd -P` does not: `-P` resolves the directory path, and
-# a script reached through a link in another directory would otherwise look for its sibling beside the
-# LINK and not find it. `readlink` without `-f` because `-f` is not portable to macOS.
-_src="${BASH_SOURCE[0]}"
-while [ -L "$_src" ]; do
-  _dir="$(CDPATH= cd -P -- "$(dirname -- "$_src")" && pwd)"
-  _src="$(readlink -- "$_src")"
-  case "$_src" in /*) ;; *) _src="$_dir/$_src" ;; esac
-done
-HOOK_DIR="$(CDPATH= cd -P -- "$(dirname -- "$_src")" && pwd)"
-HUB_ROOT="$(dirname -- "$HOOK_DIR")"
-
-# Resolution order, cheapest and most specific first: an explicit override, then the copy installed
-# in this Product, then whatever is on PATH, then a network-free npx. `--no-install` matters — a hook
-# runs on every tool call and must never pause an agent to download a package.
-CMD=()
-_yad_bin="${YAD_BIN:-}"
-if [ -n "${_yad_bin//[[:space:]]/}" ]; then
-  # Split deliberately: YAD_BIN is commonly an interpreter + script ("node /path/to/yad.mjs").
-  # The whitespace-stripped test above matters: a YAD_BIN of only spaces would leave CMD empty, and
-  # macOS's bash 3.2 treats "${CMD[@]}" on an empty array as an unbound variable under `set -u` —
-  # aborting the script with a confusing 127 instead of taking one of the branches below.
-  read -r -a CMD <<< "$_yad_bin"
-elif [ -f "$HUB_ROOT/node_modules/yadflow/bin/yad.mjs" ] && command -v node >/dev/null 2>&1; then
-  CMD=(node "$HUB_ROOT/node_modules/yadflow/bin/yad.mjs")
-elif command -v yad >/dev/null 2>&1; then
-  CMD=(yad)
-elif command -v npx >/dev/null 2>&1; then
-  CMD=(npx --no-install yadflow)
-else
-  echo "  • yad hook: no \`yad\` on PATH and none installed in $HUB_ROOT — allowing (install yadflow to re-arm the ledger guard)" >&2
-  exit 0
-fi
-
-# Belt and braces for bash 3.2's empty-array-is-unbound rule: every branch above sets CMD, but an
-# unexpanded array under `set -u` would abort the script rather than allow, so check before using it.
-if [ "${#CMD[@]}" -eq 0 ]; then
-  echo "  • yad hook: could not resolve a \`yad\` to run — allowing" >&2
-  exit 0
-fi
-
-# Run it rather than `exec`, so the exit code can be mapped. ONLY an explicit deny (2) blocks: a
-# `yad` that is present but cannot run — an `npx --no-install` with no yadflow to find, a crash, a
-# broken install — must not read as a refusal. Fail-open is the whole stance of this hook; the CI
-# gate is what fails closed.
-"${CMD[@]}" hook ledger-guard "$@"
-rc=$?
-[ "$rc" -eq 2 ] && exit 2
-if [ "$rc" -ne 0 ]; then
-  echo "  • yad hook: \`${CMD[*]} hook ledger-guard\` exited $rc — allowing (run \`yad doctor\` to check the install)" >&2
-fi
-exit 0