yadflow 4.0.0-next.3 → 4.0.0

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

@@ -11,9 +11,9 @@ 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 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) |
+| lineage-check | the `Task:` trailer → `link.md` (`epic`, which must be the story ID's prefix, + `product-repo`, read from the base — §8); 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` (`epic`, the story ID's prefix; `product-repo`, from the base — §8) → 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` (`epic`, the story ID's prefix; `product-repo`, from the base — §8) → 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`) |
@@ -22,9 +22,9 @@ repo uses. Each reads conventions established by earlier steps — it invents no
 ## Resolving `<base>` (every gate that takes one)
 
 The `<base>` argument is **optional**. The order is: the **argument**, else `SDLC_BASE`, else the
-**configured** `default_branch` (`.sdlc/hub.json`, or `SDLC_HUB_CONFIG`), else the remote's
+**configured** `default_branch` (from the Product settings file — see the next section), else the remote's
 **published default branch** (`git symbolic-ref refs/remotes/origin/HEAD`), else `origin/main` —
-the same order the CLI resolves (`cli/hubcommit.mjs`, `cli/repo.mjs`), so a gate never diffs a
+the same order the CLI resolves (`cli/productcommit.mjs`, `cli/repo.mjs`), so a gate never diffs a
 different range than the `yad` commands run beside it. Each candidate must actually **resolve**
 before it is used, so a *dangling* `origin/HEAD` (trunk renamed, the old remote-tracking ref pruned)
 falls through instead of failing the gate on a fully-fetched repo. CI always passes the base
@@ -40,6 +40,30 @@ scripts (they are standalone by design) and pinned byte-identical by a test —
 base-taking gate, including `yad-backfill`'s `backfill-check.sh` and the installed copies this repo's
 own CI runs, plus an assertion that each one actually *assigns* `BASE` from it.
 
+## Reading the Product settings (every gate that reads them)
+
+The Product's settings live under two names until v5 (E122): `.sdlc/product.json` (read first) and
+`.sdlc/hub.json` (the older name, which a gate from an older yadflow reads by path). yadflow writes both
+with identical bytes. A gate picks the file in this order:
+
+1. `SDLC_PRODUCT_CONFIG` — the environment variable to use.
+2. `SDLC_HUB_CONFIG` — the older name, still honoured.
+3. `.sdlc/product.json`.
+4. `.sdlc/hub.json` — an older Product that has only that name.
+
+The gate **FAILs**, and names both, when the two disagree:
+
+- both variables are set and name files with different contents:
+  `FAIL [product-settings]: SDLC_PRODUCT_CONFIG (…) and SDLC_HUB_CONFIG (…) name files that say different things. Set only SDLC_PRODUCT_CONFIG.`
+- neither is set, and `.sdlc/product.json` and `.sdlc/hub.json` both exist with different bytes:
+  `FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things …`. Run
+  `yad migrate --apply` in the Product (or `--apply --keep product` / `--keep hub`) to choose the copy
+  to keep, and commit both. The CLI refuses the same case with `YAD-STATE-008`.
+
+The `product_config` function is duplicated verbatim across the gates, like the base resolution above.
+Every gate stops on its failure except **risk-map**, which is advisory: there a disagreement is a
+`note [risk-map]: …` line, neither file is read, and the gate still passes (§10).
+
 ## 1. spec-link (`templates/checks/spec-link.sh`)
 
 - Checks every non-merge commit in `<base>..HEAD` **per commit** (not aggregated across the range),
@@ -54,8 +78,12 @@ own CI runs, plus an assertion that each one actually *assigns* `BASE` from it.
 - For every other commit, requires a `Task: <story>-<task>` trailer. **FAIL** if absent.
 - The trailer must be a well-formed `<story>-T<NN>` id. **FAIL** on a malformed trailer (e.g.
   `EP-demo-S01` with no `-T<NN>`) rather than letting it slip through the suffix-strip.
-- Strips the `-T<NN>` suffix from the task to get `<story>` and requires `specs/<story>/link.md` to
-  exist. **FAIL** if missing.
+- Strips the `-T<NN>` suffix from the task to get `<story>`, which must be a story ID —
+  `EP-<slug>-S<n>`, the slug in lowercase letters, digits and dashes (what `yad-stories` writes).
+  **FAIL** by name otherwise (E117 review 1): a trailer of `EP-x-S01/.-T1` named
+  `specs/EP-x-S01/./link.md`, which exists, and walked past the Product-reading gates. The four
+  Product-reading gates apply the same pattern.
+- Requires `specs/<story>/link.md` to exist. **FAIL** if missing.
 - An empty range (no non-merge commits) **PASSes**.
 - Portable across bash 3.2 (macOS) and 4+ (no `mapfile`).
 - **Fails closed** when `<base>` can't be resolved (so a shallow clone / wrong base never PASSes blind).
@@ -78,12 +106,16 @@ own CI runs, plus an assertion that each one actually *assigns* `BASE` from it.
   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).
+  `contractſ/`) is refused, and so are two story folders that are one name on a Mac
+  (`specs/EP-x-S01/` and `specs/ep-x-s01/`) — one folder there, two to rules that read exact bytes.
+  Names are folded as backfill-check folds them (E121): ASCII case plus the 13 characters a Mac folds
+  into ASCII alone (U+00DF ß and U+1E9E ẞ as `ss`, U+017F ſ as `s`, U+212A Kelvin sign as `k`, the
+  ligatures U+FB00–U+FB06 as their letters, U+037E and U+1FEF as `;` and `` ` ``), so
+  `specs/EP-<Kelvin>iosk-S01/` beside `specs/EP-kiosk-S01/` is refused. 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. Such a twin that holds a slice fails anyway: its folder is not a story
+  ID (E117). The tree is read one record per line, with a newline inside a name written as `?`, so an
+  odd file name cannot add a record.
   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,
@@ -103,14 +135,25 @@ own CI runs, plus an assertion that each one actually *assigns* `BASE` from it.
   - Best-effort fidelity: when the product repo is reachable (via `link.md`'s `product-repo` path),
     require `link.md`'s pinned `contract-lock` hash to match the product repo's current
     `contract-lock.json`. A claimed change that still pins the **old** lock **FAILS** — re-run
-    `yad-spec` so the slice matches the re-locked contract.
+    `yad-spec` so the slice matches the re-locked contract. **Where** the lock is read from is not the
+    PR's to choose (E117) — see "Resolving `product-repo`" in §8.
+  - Each story's slice must sit under a story ID (`specs/EP-<slug>-S<n>/contracts/`) and come with its
+    `specs/<story>/link.md` — `yad-spec` writes the two together. A slice that is **added or changed**
+    without them **FAILS** by name (E117 review 2): deleting `link.md` used to drop a stale pin, and a
+    Spec Kit folder such as `specs/001-name/contracts/` can be tied to no lock. A non-story folder
+    whose changed files are all **deletions** passes, so it can always be cleaned up. A story may drop
+    its `link.md` only when its **whole** slice is gone at HEAD (review 3): deleting `link.md` with part
+    of a slice left the rest with nothing pinning it. This closes the deferral E115 stated as a cost.
+  - When the Product folder **was reached** and has no `epics/<epic>/`, the slice is an **orphan** and
+    **FAILS** — it used to say "not reachable" and defer. Removing an orphan's slice (deletions only)
+    passes: no lock exists for it to contradict.
   - The fidelity check runs for **every story whose slice the diff touches**, and **aggregates**: each
     story reports (matched / stale / deferred), and any stale pin fails the gate. `git diff
     --name-only` is path-sorted, so reading one story off the first changed path validated whichever
     story sorted first and left the rest unpinned — a later story pinning a stale hash passed, and a
     first story with no `link.md` deferred the whole check before the stale one was ever read
     (issue #161). One clean-or-deferred story never masks another's stale pin, the same rule spec-link
-    applies per commit.
+    applies per commit. (A story with no `link.md` now FAILs rather than defers — see above.)
   - 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.
@@ -199,7 +242,7 @@ No unsigned commits reach merge — on the Product and on every connected repo.
 
 **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
+and `yad setup` no longer generate `.sdlc/verified-authors`, and no gate reads it or the Product settings'
 `verified_authors` any more (`SDLC_VERIFIED_AUTHORS` is gone too). When an old `.sdlc/verified-authors`
 file is still on disk, the gate prints:
 
@@ -240,9 +283,10 @@ non-merge commit in `<base>..HEAD`:
 - **Subject** must be `<type>: <description>` with `<type>` a known Conventional-Commits type
   (`feat|fix|docs|refactor|test|perf|build|ci|chore|revert` — keep in sync with `cli/manifest.mjs`
   `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`.
+- **Trailers**, when present, appear in the fixed order `Task → Contract-Change → Ledger-Override →
+  Co-Authored-By` (`Ledger-Override` only from `yad commit --manual --reason`; this gate does not check it).
 - Merge/squash commits (2+ parents) are skipped — their platform-generated subjects are not authored.
-- **Profiles** (`--profile code|hub|product`): the subject rule is identical on both; the gate never requires
+- **Profiles** (`--profile code|product`; `hub`, the old name for `product`, still works): 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).
@@ -255,7 +299,7 @@ from the event payload):
 - `--profile code` (default) → a Conventional-Commits subject `<type>: <description>`, no trailing
   period (`config.yaml build.pr_title_style: same_as_commit_subject` — one task = one PR, the title is
   the squash-merge subject).
-- `--profile hub` → splits by the PR/MR **head branch** (passed via `--head`, injected by CI):
+- `--profile product` (old name `hub`, still accepted) → 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 Product itself, so it follows the `code` convention (a
@@ -280,7 +324,7 @@ catches a free-form description that bypassed it:
 
 - `--profile code` (default) → requires `## Summary`, `## Impact & Risk`, `## Checklist`, and a filled
   `Risk level:` (`low|medium|high`).
-- `--profile hub` → splits by the PR/MR **head branch** (passed via `--head`, injected by CI):
+- `--profile product` (old name `hub`, still accepted) → 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 Product tooling PR, so it requires the `code` task template (`## Summary`,
@@ -295,7 +339,7 @@ the author then reads "does not use the template" while looking at a description
 it (#164). GitHub is unaffected (`github.event.pull_request.body` is not truncated). Two mitigations,
 both shipped:
 
-- the GitLab MR templates (`yad-pr-template` `templates/gitlab/…` and `templates/hub/gitlab/…`) carry
+- the GitLab MR templates (`yad-pr-template` `templates/gitlab/…` and `templates/product/gitlab/…`) carry
   the constraint as a comment and keep every required section early, so a truncated body still passes;
 - when a required section is missing **and** the body it read is ≥ 2700 characters, the gate prints a
   `NOTE` naming the truncation and the fix — reorder the required sections above the cutoff and push
@@ -324,6 +368,50 @@ 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.
 
+**The PR under check does not choose where the Product is read from (E117).** `link.md` is a file the
+PR's own author writes. Before E117 a PR could point `product-repo` at a path that does not exist — the
+gate called the Product "not reachable" and passed — or at a folder it committed itself, holding a
+hand-made `contract-lock.json` with the hash it pins. Two rules close both:
+
+| Rule | What the gate does | Why |
+| --- | --- | --- |
+| The repo's **record** comes first (E120) | `.sdlc/product-link.json` in the code repo — `git_url`, `path` (from the repo root: where CI checks the Product out, `.yad/product` by default) and `default_branch` — is written by `yad check --fix` / `yad update` from the Product and merged on its own. Read from the **base**, its `path` wins over every `link.md`: no gate takes where the Product lives from the PR. A record the PR adds or changes counts once it merges (a note says so). A `link.md` whose own `product-repo` reaches a **different** folder here gets a note; one that reaches nothing (a path on its author's machine) is passed over in silence. When the record's path reaches nothing — a developer's own run, where nobody cloned into it — the base's `link.md` order below is used if **it** reaches a folder (still the base's, never the PR's); otherwise the record stands and the gate **defers** (CI has no Product checkout) — it is not the PR's choice, so E119's first-spec FAIL does not apply. With no record on the base, the order below is kept. | A record is one reviewed fact for the whole repo, where `link.md` is one per story and written by each PR's author. |
+| `product-repo` comes from the **base** | Where the Product lives is a fact about the whole repo, so the value is, in order: `link.md` as it stands on the base; else a sibling `specs/<story>/link.md` on the base (a story new in this PR, or a `link.md` that never had a value) — one of the same epic first, and the first whose value reaches a folder here, so one stale `link.md` cannot hand every new story a deferral; else — the repo's first spec — the PR's value. A PR whose value differs gets a note (`… names product-repo 'Y', but specs/<other>/link.md on main says 'X' — the Product is read from the base value; a new one counts once it merges`). | Only `product-repo` is read from the base. `contract-lock` is read as the PR leaves it — a re-spec PR must update the pin. |
+| A **kept** Product is read from the **base commit** | Whether the Product is kept in this repo (a monorepo: the Product and the code in one git repo) is asked of the **base**, from the path's text alone, before anything on disk: the base tracks `<path>/.sdlc/product.json` or `<path>/.sdlc/hub.json` (both, until v5), which every Product commits. The disk is the PR's — a PR that deleted or moved the folder read as untracked, and deferred. Its `epics/` is then written out from the base commit through a throwaway index (`git read-tree` + `git checkout-index`), with the work tree pointed at an empty temp folder, and read from there. Not `git archive`, which drops whatever `.gitattributes` marks `export-ignore`; and not with the real work tree, whose `.gitattributes` is the PR's — `*.md text eol=crlf` or `working-tree-encoding=UTF-16` there wrote the base's files unreadable. A symlink or submodule inside the base's `epics/` is **FAIL** by name: a link written out still points where it pointed (an absolute one into the PR's working tree), and a submodule comes out as an empty folder. Any other tracked file under a Product path — a planted folder, or one file force-added under an ignored checkout — **FAILs** by name, with the fix (`git rm -r --cached`). A path that runs through a tracked symlink, submodule or file: **FAIL** by name. The path is walked twice — part by part as written, and again from where it really lands, resolved in one step from the gate's own shell — so an alias such as Linux's `/proc/self/cwd`, which means a different folder to each process, cannot lead the gate into the PR's own tree (review 5). A folder that is there but cannot be entered to find where it really is **FAILs** rather than being read unchecked (review 6). A path whose real location is inside the repo's own git folder also **FAILs**: git never lists `.git/` as tracked, yet branch names shape the folders in it (review 7). The git folder is compared as a folder, not a spelling, so `.GIT` counts on a disk that ignores case (review 8). | "Inside the code repo" is not the test. CI can only check a second repo out inside the workspace (`actions/checkout` `path:`), and an untracked checkout there is not the PR's. |
+| One story ID shape | A story must be `EP-<slug>-S<n>` (lowercase slug), in all four gates and spec-link. **FAIL** by name otherwise. | A story written as a path (`EP-x-S01/.`) named a `link.md` the base read never found. |
+
+The costs, stated: in a monorepo the Product is read from the base, so a PR that re-locks the contract
+**and** changes the slice fails the pin check — merge the re-lock first, the rule the gate already states
+("re-locked upstream first"); and a PR that adds a new epic or story **and** its code fails
+contract-check, lineage-check, epic-open and reconcile-debt as an orphan — merge the Product change
+first. When `product-repo` reaches **nothing** — neither a kept Product by its text nor any folder on
+disk — a Product the base keeps (a tracked `.sdlc/product.json` or `.sdlc/hub.json` with an `epics/` folder beside it) that holds
+the story's epic is the one read: a value spelled past the repo's own folder name, or another machine's
+absolute path, cannot be folded to it, and a PR that deleted or moved it left nothing on disk to walk
+(review 3). Only then, and only one holding the epic (review 4): a kept Product used to win over the
+real checkout, so a merged test fixture shaped like a Product was read instead. Two that hold it
+**FAIL**. In a two-repo setup whose CI checks nothing out, a fixture that does hold the epic is read
+where the gate used to defer — no weaker than that deferral. A kept Product's `.gitattributes` entries
+are dropped before it is written out. Frontmatter is read with CR
+stripped before the `---` fences are matched, so a CRLF Product reads the same as an LF one. The case of a path is folded only where git folds it
+(`core.ignorecase`, a Mac checkout), and in ASCII only. A Product absent from CI still defers with a note, as
+before — with one exception in contract-check (E119): on a repo's **first spec**, where no `link.md` on the
+base names a Product and `product-repo` is the PR's own value, a diff that changes a slice and whose
+`product-repo` reaches nothing **FAILs** by name ("… is this repo's first spec …", then "… reaches
+nothing", or "… names no product-repo" when `link.md` has none). A Product that IS reached — checked out, or
+kept in this repo and read from the base — but holds the epic's folder with no ledger in it still defers:
+it is not "nowhere", and the PR cannot shape a base copy. A first
+spec with no slice is unchanged (the surface is read from paths alone), and so is one that only removes a
+slice. **Cost:** a repo whose CI does not check out the Product cannot merge a first spec that carries a
+slice until it does. The other three gates judge the epic, not the surface, and still defer there (E120). `yad doctor` warns `checks:product-path-blind` for an older copy of any of the four.
+
+**The PR does not choose the epic either (E118).** lineage-check, epic-open and reconcile-debt-check
+read `epic:` from `link.md`. It must equal the story ID's prefix — story `EP-checkout-S01` belongs to
+epic `EP-checkout`, which is what `yad-spec` writes. Any other value — an empty or missing one
+included — **FAILs** by name. Before E118 a
+story of a sealed epic could name an open one and pass epic-open. contract-check has always worked the
+epic out from the story ID.
+
 - **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
@@ -334,7 +422,8 @@ four copies stay byte-identical.
   `shipped`. A commit whose owning epic is sealed **FAILS**: new behaviour cannot mutate a shipped epic;
   it must land in a new threaded change-epic. This is what stops the Shape artifacts from going stale.
 - **reconcile-debt** — resolves the epic's `thread` (its `thread:` frontmatter, else the epic id) and
-  scans every thread epic's `reconcile-debt.json`. An **open** entry the current epic does not own
+  scans every thread epic's `reconcile-debt.json`. A Product that was reached with no such epic **FAILs** as an orphan story
+  link, as lineage-check and epic-open do (E117 review 2). An **open** entry the current epic does not own
   **FAILS** the change (the thread is frozen until the hotfix debt is paid: artifacts updated + a
   regression test added, then `status: paid`). Thread-scoped — only the affected thread freezes.
 
@@ -493,6 +582,15 @@ The gates run identically under either CI; the config just invokes the scripts w
   Dependencies are cached with `actions/cache` (npm's `~/.npm`, pnpm's store, and the Corepack home
   holding the pinned manager, keyed on the lockfiles and package.json) rather than setup-node's
   npm-only `cache:`, which must name the manager before package.json has been read.
+- **Pinned actions, read-only token.** Every `uses:` in the GitHub templates names a commit SHA, with
+  the version after it in a comment (`actions/checkout@<sha> # v4.4.0`). A tag such as `@v4` can be
+  moved to other code; a SHA cannot. Each workflow also sets a top-level `permissions:` block that is
+  read-only, so no job gets write access unless it asks for it. If your own Dependabot bumps a SHA in
+  an installed copy that `.sdlc/managed.json` records, `yad check` then reports that file as
+  `modified`, and `yad update` keeps your copy rather than overwriting it — so that file stops
+  receiving template changes. (`--overwrite-local` replaces it after saving `<file>.yad-orig`; a copy
+  with no record reads as `outdated`, and a plain `yad update` replaces it, saving `<file>.yad-orig`
+  first.) To stay on the template, leave the pins to yadflow releases.
 - **GitLab CI** — `templates/gitlab/yad-checks.gitlab-ci.yml` → `.gitlab/ci/yad-checks.yml`, pulled in
   by the root `.gitlab-ci.yml`'s `include:`. The jobs run on `merge_request_event` with `GIT_DEPTH: 0`,
   passing `origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME`; the pattern jobs read `$CI_MERGE_REQUEST_TITLE`
@@ -505,6 +603,47 @@ The gates run identically under either CI; the config just invokes the scripts w
   (`templates/gitlab/.gitlab-ci.yml`) carries the same Node default, exact Nx range, and dependency
   installer and test-worker-cap semantics. All `--profile code`.
 
+### Checking the Product out in CI (E120)
+
+The four Product-reading gates can only read a Product that is on disk. Before each of them, both
+workflows run `checks/product-checkout.sh` (wired into every code repo). It reads
+`.sdlc/product-link.json` **from the base** — never as the PR leaves it — and, when the
+`YAD_PRODUCT_TOKEN` secret is set, clones the Product's `default_branch` (depth 1; the remote's own default when the record names
+none) into the record's `path`. To turn it on:
+
+1. From the Product, run `yad check --fix --push`: it writes `.sdlc/product-link.json` into each
+   connected code repo and commits it to the default branch. Set the Product's `git_url` in its
+   `.sdlc/product.json` first (`yad setup` fills it from the `origin` remote). On a Product that has only
+   `.sdlc/hub.json`, set it there, and never create a `product.json` beside it by hand; when both exist,
+   run `yad migrate --apply --keep product` after the edit.
+2. Make a token that can **read** the Product repository — on GitHub a fine-grained personal access
+   token or a GitHub App token with `contents: read` on that one repo (the workflow's own `GITHUB_TOKEN`
+   cannot read another private repo); on GitLab a project or group access token with `read_repository`.
+3. Add it to the **code repo** as the `YAD_PRODUCT_TOKEN` secret (GitHub: Settings → Secrets and
+   variables → Actions; GitLab: Settings → CI/CD → Variables, **masked**).
+
+**Who can read the token.** The workflow runs on the PR's own copy of `checks/product-checkout.sh`, so
+anyone who can push a branch to the code repo can read `YAD_PRODUCT_TOKEN` — edit the script, open a
+PR. (A PR from a fork gets no secret, and defers.) So give it **read** access to the Product repository
+and nothing else. On GitLab, a variable marked **protected** is not handed to pipelines of unprotected
+branches, so merge requests from feature branches would defer: leave it unprotected, masked, and
+read-only.
+
+What it does in each case:
+
+| Case | Result |
+| --- | --- |
+| No record on the base, no `YAD_PRODUCT_TOKEN` (every PR from a fork), or no `git_url` in the record | A note; nothing is cloned, and the gates defer as before. |
+| The record's `path` is outside the repo, `.`, absolute, or under `.git` | **FAIL** — CI can only check a second repo out inside the workspace. |
+| A folder on the way to `path` is a symlink (one the PR tracks, say) | **FAIL** — git would clone through it, to wherever it points. |
+| The `path` holds files this repo tracks | **FAIL** — the gates refuse a tracked Product path anyway. |
+| The folder is already there | Left as it is. |
+| The clone fails with a token set | **FAIL**, naming the URL and branch — a broken setup must not read like a deferral. |
+
+The token is handed to git through its environment (`GIT_CONFIG_COUNT`, git 2.31+) as an HTTP header,
+never on a command line or in a URL; on GitHub the encoded form is masked too. An `ssh` `git_url`
+(`git@host:org/repo.git`) is cloned as the same repo over `https`.
+
 ## Sync with existing CI (merge, never clobber)
 
 `wire` is **additive**: it brings the SDLC gates into a repo that may already have CI, without ever
@@ -534,15 +673,23 @@ 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 Product (`repo: hub`)
+## Wiring the Product (`repo: product`)
 
-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
+The Product is itself a repo on a platform (recorded in `.sdlc/product.json` by
+`yad-connect-repos action: detect-product`). `wire repo: product` targets `{project-root}` and uses the same
 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:
+`pr-title`, `pr-template` and `ledger-guard` in `yad-product-checks`, `verified-commits` in its own workflow,
+and the `yad-update-guard`. On GitHub the `ledger-guard` job is given **no** `GH_TOKEN` on purpose: its
+bot exemption checks the author text and the Verified badge, and the badge proves only that the
+*committer* signed, so any contributor who signs could claim the bot's name. Without a token the badge
+lookup fails and every bot-attributed commit that changes a ledger file is refused — safe, because the
+gate-sync bot pushes only to the review PR's base (normally the default branch), never to a PR. This
+holds on GitHub-hosted runners; a self-hosted runner with a stored `gh auth login` would answer the
+lookup anyway. (On GitLab a project CI/CD variable reaches every job, so
+the `GITLAB_TOKEN` / `SDLC_API_TOKEN` that verified-commits needs reaches ledger-guard too, and the gap is
+open there.) 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
@@ -561,21 +708,21 @@ The Product **does** run the verified-commits gate — `yad check --fix` install
 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
+its one include line) whenever `.sdlc/product.json` has a platform with a verified ledger. So the
 Shape review PRs are held to the same rule as code-repo PRs: platform-Verified signatures only.
 
 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
+`--profile product`. 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 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
+(`templates/github/yad-product-checks.yml` → `.github/workflows/yad-product-checks.yml`, or the GitLab fragment
+`templates/gitlab/yad-product-checks.gitlab-ci.yml` → `.gitlab/ci/yad-product-checks.yml` + its one include
 line). Code repos run the same three with `--profile code` inside the main `yad-checks` workflow.
 
-## The agent guardrail (`templates/hooks/ledger-guard.sh` + `yad hook ledger-guard`)
+## The agent guardrail (`templates/hooks/ledger-guard.mjs` + `yad hook ledger-guard`)
 
 Not a CI gate — a **harness hook**, and the only piece of yadflow that runs *inside* an agent's tool
 loop. It exists because of the gap #171 reported: `checks/ledger-guard.sh` is correct and blocking,
@@ -595,21 +742,29 @@ Two harnesses match that contract, and `yad check --fix` wires both:
 
 | 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` |
+| Claude Code | `.claude/settings.json` | `PreToolUse` | `node "$CLAUDE_PROJECT_DIR/hooks/ledger-guard.mjs"` |
+| Cursor | `.cursor/hooks.json` | `preToolUse` | `node hooks/ledger-guard-cursor.mjs` |
+
+Any other harness that can run a command and read those two exit codes can use
+`node <product>/hooks/ledger-guard.mjs` by hand.
 
-Any other harness that can run a command and read those two exit codes can use `ledger-guard.sh` by
-hand.
+**Node scripts, not shell scripts (E113).** Every hook was a bash script until E113; each is now a
+dependency-free Node script, so it runs on Windows as it does on macOS and Linux, and needs no execute
+bit. Each finds the Product from its own location, never from a harness variable. On Windows, Claude
+Code runs hook commands in Git Bash (PowerShell without it, where the entry does not run), and Cursor
+runs them through PowerShell, which runs `node hooks/<script>.mjs` as it is. An entry naming an old
+`hooks/*.sh` is rewritten by `yad check --fix`, and the old script is deleted when `.sdlc/managed.json`
+proves yad wrote it unedited and no settings file still runs it.
 
 **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
+hook's schema blocks the action". `ledger-guard.mjs` 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
+So Cursor gets `hooks/ledger-guard-cursor.mjs`, installed only for a project whose targets include
+`.cursor`. It calls `yad hook ledger-guard --format cursor` itself and guarantees a
 permission answer on stdout, whatever happens:
 
 | | stdout | exit |
@@ -631,18 +786,18 @@ as the code for "no JSON to read", so it would discard the reason — and naming
 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
+The wrapper takes **no arguments**, and every fail-open branch (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`
+empty stdout that would block. **Exit 2 is converted into a deny**, not an allow: the wrapper
 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`
+The two commands are spelled differently on purpose. Claude Code runs the string through a shell (Git
+Bash on Windows), 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 which
+shell runs the command — PowerShell on Windows — so its entry is `node` and a relative path, with no
+variable and no quotes: PowerShell reads neither. 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*
@@ -654,14 +809,14 @@ 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
+**Layering.** `hooks/ledger-guard.mjs` 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.
+logic is unit-tested (`cli/hook.mjs`, `cli/test.mjs`; the scripts in `cli/test-hooks.mjs`, on Windows too).
 
 **Scope — identical to the CI gate, on purpose**, down to the details that decide the hard cases:
 
-- Guarded: `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` and `epics/*/reviews/*.md`.
+- Guarded: `epics/*/.sdlc/{state,approvals,comments,product-prs,hub-prs}.json` and `epics/*/reviews/*.md`.
   Exempt: `contract-lock.json` (artifact-side), `change.json`, every artifact.
 - **Depth matches the gate's globs.** Its arms are bash `case` patterns, and a bash `*` spans `/`, so
   `epics/EP-a/nested/.sdlc/state.json` is guarded there — and here. Being stricter locally would let
@@ -683,10 +838,15 @@ logic is unit-tested (`cli/hook.mjs`, `cli/test.mjs`) instead of living in bash.
   nothing is wired or blocked.
 
 **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,
+an unreadable `product.json` / `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
 protects the ledger; this only shortens the feedback loop. `YAD_HOOK_DISABLE=1` skips one command.
+The door for a PERSON is `yad commit --manual --reason "<why>"` (E49): it skips the local hook for that
+one commit and records the reason as a `Ledger-Override:` trailer. `ledger-guard` in CI still FAILS the
+commit — anyone can type a trailer — and prints the reason under the FAIL. Each line starts with the commit's sha, and every control character (a
+carriage return, an escape) becomes a space, so an author's text never starts a line GitHub Actions would
+read as a workflow command (indenting alone would not do it: the runner skips leading spaces). The author names and file paths it prints get the same cleaning (a newline in a path becomes a space too).
 
 **Known gaps** — both fall through to the CI gate, which is why it stays the authority:
 
@@ -703,7 +863,7 @@ protects the ledger; this only shortens the feedback loop. `YAD_HOOK_DISABLE=1`
 
 | Path | Owner |
 |---|---|
-| `<product>/hooks/ledger-guard.sh` | fully managed — drift-checked and recorded in `.sdlc/managed.json` like any gate script |
+| `<product>/hooks/ledger-guard.mjs` | 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:
@@ -712,7 +872,7 @@ The settings file is the team's, so the rules around that one entry are delibera
   substring. A team keeping its own wrapper at `.claude/hooks/ledger-guard.sh` would otherwise have
   their hook silently rewritten to ours, on the `outdated` path that takes no backup. Matching
   exactly means the worst case is a second entry (the guard runs twice, harmlessly).
-- **The command is quoted** (`"$CLAUDE_PROJECT_DIR/hooks/ledger-guard.sh"`) because the harness runs
+- **The path is quoted** (`node "$CLAUDE_PROJECT_DIR/hooks/ledger-guard.mjs"`) because the harness runs
   it through a shell: unquoted, a project path containing a space word-splits and the guard is
   silently off while `check` and `doctor` still call it wired.
 - **A file that does not parse is never rewritten** — not even by `--overwrite-local`. For a managed

package/skills/yad-checks/templates/checks/commit-message.sh

@@ -7,13 +7,37 @@
 #   - any trailers appear in the fixed order Task -> Contract-Change -> Co-Authored-By.
 # Keep the type list in sync with cli/manifest.mjs COMMIT_TYPES and config.yaml build.commit_subject_style.
 #
-# Profiles (--profile code|hub|product, default code): the subject rule is identical on the Product and on
+# Profiles (--profile code|product, default code; `hub` is the old name for product): the subject rule is identical on the Product and on
 # code repos (both follow CONTRIBUTING). The Task trailer is NOT required here (the spec-link gate owns
 # that on code repos; Product commits are not task-scoped) — this gate only checks SHAPE and ORDER.
 #
 # Merge/squash commits (2+ parents) are skipped: their platform-generated subjects are not authored.
 set -euo pipefail
 
+# --- shared Product settings file (byte-identical across the gates; they are standalone by design, so
+# --- it is duplicated, not sourced) ---
+# The Product's settings live under two names until v5: `.sdlc/product.json`, read first from 4.0, and
+# `.sdlc/hub.json`, which an older yadflow wrote and its gates read. The environment may name the file
+# instead: SDLC_PRODUCT_CONFIG, or the older SDLC_HUB_CONFIG. Two names that say different things are
+# never settled by picking one — the CLI refuses the same way (YAD-STATE-008) — so the gate FAILS and
+# names both. Said on stderr and returned as a failure: this runs inside `$(...)`, where an `exit` would
+# only leave the subshell. `cmp -s` is byte for byte, like the CLI's own comparison.
+product_config() {
+  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ] && [ -n "${SDLC_HUB_CONFIG:-}" ] \
+    && [ "$SDLC_PRODUCT_CONFIG" != "$SDLC_HUB_CONFIG" ] && ! cmp -s "$SDLC_PRODUCT_CONFIG" "$SDLC_HUB_CONFIG"; then
+    echo "FAIL [product-settings]: SDLC_PRODUCT_CONFIG (${SDLC_PRODUCT_CONFIG}) and SDLC_HUB_CONFIG (${SDLC_HUB_CONFIG}) name files that say different things. Set only SDLC_PRODUCT_CONFIG." >&2
+    return 1
+  fi
+  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ]; then printf '%s' "$SDLC_PRODUCT_CONFIG"; return 0; fi
+  if [ -n "${SDLC_HUB_CONFIG:-}" ]; then printf '%s' "$SDLC_HUB_CONFIG"; return 0; fi
+  if [ -f .sdlc/product.json ] && [ -f .sdlc/hub.json ] && ! cmp -s .sdlc/product.json .sdlc/hub.json; then
+    echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. Run \`yad migrate\` in the Product to choose the copy to keep, and commit both." >&2
+    return 1
+  fi
+  if [ -f .sdlc/product.json ]; then printf '%s' .sdlc/product.json; else printf '%s' .sdlc/hub.json; fi
+}
+PRODUCT_CONFIG="$(product_config)" || exit 1
+
 PROFILE=code
 ARGS=()
 while [ $# -gt 0 ]; do
@@ -23,27 +47,29 @@ while [ $# -gt 0 ]; do
     *) ARGS+=("$1"); shift ;;
   esac
 done
-case "$PROFILE" in code|hub|product) ;; *) echo "FAIL [commit-message]: unknown --profile '$PROFILE' (code|hub|product)."; exit 1 ;; esac
-# `product` is the new name for the `hub` profile and BOTH are accepted.
+case "$PROFILE" in code|hub|product) ;; *) echo "FAIL [commit-message]: unknown --profile '$PROFILE' (code|product, or hub, the old name for product)."; exit 1 ;; esac
+# `product` is the Product's profile. `hub` is its old name, and BOTH are accepted.
 #
-# Not because the two sides update separately — they do not: this script and the workflow that passes
-# the flag are both in PRODUCT_WIRING (cli/manifest.mjs) and land together on one `yad update`. It is
-# the plain add-before-remove ladder instead: accept the new spelling now, switch the workflow
-# templates to emit it in a later release, drop the old one after that. Every shipped template still
-# passes `--profile hub` today, so this arm is dead weight until that switch — which is the point.
+# This script and the workflow that passes the flag are both in PRODUCT_WIRING (cli/manifest.mjs) and
+# normally land together on one `yad update` — but not always: a copy the team edited is kept. So the
+# order is add-before-remove: the new spelling was accepted first, the workflow templates switched to
+# emit it in E123 (`yad-product-checks.yml`), and the old one is dropped after that. `hub` stays
+# accepted meanwhile, for a workflow of the team's own or one they edited. The other direction — an
+# edited copy of THIS script from before 4.0, which rejects `product`, beside the new workflow — fails
+# every Product PR; `yad update` and `yad doctor` (`profile:`) say so.
 #
-# Normalised to `hub` immediately, so nothing below has to know there are two spellings. That is
-# load-bearing in pr-title.sh and pr-template.sh: leave `$PROFILE` as `product` and the `= hub`
+# Normalised to `product` immediately, so nothing below has to know there are two spellings. That is
+# load-bearing in pr-title.sh and pr-template.sh: leave `$PROFILE` as `hub` and the `= product`
 # branch is skipped, taking the whole review-branch arm with it — including the guard that stops a
 # plain code title carrying an artifact change past its review.
-[ "$PROFILE" = product ] && PROFILE=hub
+[ "$PROFILE" = hub ] && PROFILE=product
 
 
 # --- shared base resolution (byte-identical across the gates; they are standalone by design, so it
 # --- is duplicated, not sourced) ---
 # With no explicit base, RESOLVE the trunk instead of assuming a hardcoded `origin/main` — on a repo
 # whose trunk is `develop`/`master` that guess either fails closed or, where a stale `main` still
-# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/hubcommit.mjs,
+# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/productcommit.mjs,
 # cli/repo.mjs): the CONFIGURED default_branch first, then the remote's published default
 # (origin/HEAD), then origin/main. Each candidate must actually resolve before it is used, so a
 # DANGLING origin/HEAD (trunk renamed, the old remote-tracking ref pruned) falls through to the next
@@ -52,7 +78,7 @@ case "$PROFILE" in code|hub|product) ;; *) echo "FAIL [commit-message]: unknown
 # command substitution in an assignment aborts the script.
 resolve_base() {
   # tr first: a key and its value may legally sit on separate lines, which a per-line match misses.
-  _cfg="$(tr -d '\n' < "${SDLC_HUB_CONFIG:-.sdlc/hub.json}" 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
+  _cfg="$({ tr -d '\n' < "$PRODUCT_CONFIG"; } 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
   _head="$(git symbolic-ref --short --quiet refs/remotes/origin/HEAD 2>/dev/null)" || _head=""
   for _c in "origin/${_cfg}" "${_head}" origin/main; do
     case "$_c" in ''|origin/) continue ;; esac