yadflow 3.18.1 → 4.0.0-next.1

package/skills/yad-checks/templates/checks/build-test-lint.sh

@@ -1,26 +1,44 @@
 #!/usr/bin/env bash
 # build / test / lint gate (Phase 3 build plan §C).
 # Standard quality stage: lint, build, and tests that actually exercise behavior (not just pass).
-# Delegates to the repo's npm scripts so each repo owns the specifics.
+# Delegates to the package manager named by package.json so each repo owns the specifics.
 set -euo pipefail
 
+YAD_CHECKS_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+readonly YAD_CHECKS_DIR
+# shellcheck source-path=SCRIPTDIR
+# shellcheck source=package-manager.sh
+source "$YAD_CHECKS_DIR/package-manager.sh"
+# Two assignments on purpose: nested inside another $(...), a failing yad_package_manager_spec would
+# be swallowed, and the gate would fall back to lockfile detection and PASS on a package.json it
+# had just rejected. Each step fails the gate on its own under `set -e`.
+package_manager_spec="$(yad_package_manager_spec)"
+package_manager="$(yad_detect_package_manager "$package_manager_spec")"
+# `npm`, `pnpm`, or `corepack npm` for a pinned npm — see yad_package_manager_command.
+run_with_words="$(yad_package_manager_command "$package_manager_spec" "$package_manager")"
+read -r -a run_with <<< "$run_with_words"
+
 echo "[build/test/lint] lint…"
-npm run --silent lint
+"${run_with[@]}" run --silent lint
 echo "[build/test/lint] build…"
-npm run --silent build
+"${run_with[@]}" run --silent build
 
 # Worker cap: when YAD_TEST_MAX_WORKERS is set AND the repo's test script is jest/vitest (the
 # runners that accept --maxWorkers), forward it to bound CI test concurrency. For any other runner
 # (node --test, mocha, …) it is a deliberate no-op so the gate never breaks on an unknown flag.
+# npm needs the `--` separator to hand the flag to the script; pnpm (7+) forwards a literal `--` to
+# the script instead, where jest reads `--maxWorkers=N` as a test-path pattern and finds no tests.
 extra=""
 if [ -n "${YAD_TEST_MAX_WORKERS:-}" ]; then
-  case "$(npm pkg get scripts.test 2>/dev/null || true)" in
-    *jest*|*vitest*) extra="-- --maxWorkers=${YAD_TEST_MAX_WORKERS}" ;;
+  case "$(node --input-type=module -e 'import fs from "node:fs"; const p=JSON.parse(fs.readFileSync("package.json", "utf8").replace(/^\uFEFF/, "")); process.stdout.write(p.scripts?.test || "")' 2>/dev/null || true)" in
+    *jest*|*vitest*)
+      if [ "$package_manager" = "pnpm" ]; then extra="--maxWorkers=${YAD_TEST_MAX_WORKERS}"; else extra="-- --maxWorkers=${YAD_TEST_MAX_WORKERS}"; fi
+      ;;
   esac
 fi
 echo "[build/test/lint] test…"
-# Intentional word-splitting: $extra is either empty or `-- --maxWorkers=N`.
+# Intentional word-splitting: $extra is empty, `-- --maxWorkers=N` (npm), or `--maxWorkers=N` (pnpm).
 # shellcheck disable=SC2086
-npm run --silent test $extra
+"${run_with[@]}" run --silent test $extra
 
 echo "PASS [build/test/lint]: lint, build, and tests all green."

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

@@ -7,9 +7,9 @@
 #   - 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, default code): the subject rule is identical on the product hub and on
+# Profiles (--profile code|hub|product, default code): 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; hub commits are not task-scoped) — this gate only checks SHAPE and ORDER.
+# 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
@@ -23,7 +23,21 @@ while [ $# -gt 0 ]; do
     *) ARGS+=("$1"); shift ;;
   esac
 done
-case "$PROFILE" in code|hub) ;; *) echo "FAIL [commit-message]: unknown --profile '$PROFILE' (code|hub)."; exit 1 ;; esac
+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.
+#
+# 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.
+#
+# 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`
+# 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
+
 
 # --- shared base resolution (byte-identical across the gates; they are standalone by design, so it
 # --- is duplicated, not sourced) ---

package/skills/yad-checks/templates/checks/contract-check.sh

@@ -47,6 +47,21 @@ RANGE="${BASE}..HEAD"
 changed="$(git -c core.quotePath=false diff --name-only "$RANGE")"
 surface="$(printf '%s\n' "$changed" | grep -E '^specs/[^/]+/contracts/' || true)"
 
+# Slice paths this diff DELETES. `--name-only` above lists a deleted file exactly like a changed one,
+# which is right for the trailer rule — removing an agreed endpoint IS a surface change — but it
+# creates a dead end for the one epic that should never have had a slice in the first place.
+#
+# A short-lane epic has no lock and never will (E40). Once a `specs/<story>/contracts/` file exists
+# under one, the unflagged rule below fails the commit, the no-lock rule further down fails the
+# flagged one, and the cleanup commit that DELETES the file fails too — so there is no diff that
+# passes, including the correct one. An escape hatch is not optional there.
+#
+# Deleting your own copy of a surface that nothing upstream has locked cannot widen it: with no lock
+# there is no agreed shape for the deletion to contradict. So a delete-only diff is allowed through
+# the no-lock branch (and only that branch — where a lock EXISTS, a deletion is still a real surface
+# change and every rule below applies to it unchanged).
+deleted="$(git -c core.quotePath=false diff --diff-filter=D --name-only "$RANGE" | grep -E '^specs/[^/]+/contracts/' || true)"
+
 if [ -z "$surface" ]; then
   echo "PASS [contract-check]: diff does not touch the contract surface (specs/*/contracts/**)."
   exit 0
@@ -59,6 +74,8 @@ cc="$(git log "$RANGE" --format='%(trailers:key=Contract-Change,valueonly)' | se
 if ! printf '%s\n' "$cc" | grep -qx 'yes'; then
   echo "FAIL [contract-check]: contract surface changed without a 'Contract-Change: yes' trailer."
   echo "  -> Route back to the architecture gate: update + re-lock contract.md in the product repo,"
+  echo "     or, if this epic is on a short lane (chore/spike) and has no architecture gate, move the"
+  echo "     surface change to a new epic on the classic route,"
   echo "     re-run yad-spec, then implement with Contract-Change: yes. The surface is never widened"
   echo "     from inside a code repo."
   exit 1
@@ -74,7 +91,7 @@ fm_val() { awk -v k="$1" 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f &&
 # Same, for a link.md field. yad-spec writes link.md WITH frontmatter, but code repos still carry
 # pre-frontmatter ones that contract-check used to read with a whole-file scan — so fall back to that
 # rather than silently reading an empty value and skipping the check it guards. Deliberately separate
-# from fm_val: hub artifacts (epic.md, stories/*.md) stay bounded to their first block.
+# from fm_val: Product artifacts (epic.md, stories/*.md) stay bounded to their first block.
 link_val() {
   _v="$(fm_val "$1" "$2")"
   [ -n "$_v" ] || _v="$(sed -nE "s/^$1:[[:space:]]*(.*)\$/\1/p" "$2" 2>/dev/null | head -1 | tr -d '\r' | sed -E 's/[[:space:]]+$//')"
@@ -146,6 +163,45 @@ while IFS= read -r story; do
       continue
     fi
     echo "note [contract-check]: ${link} hash matches the product lock (${current:0:12}…)."
+  elif [ -n "$prod" ] && [ -d "${prod}/epics/${epic}/.sdlc" ]; then
+    # THE PRODUCT REPO RESOLVED AND THERE IS STILL NO LOCK. That is a different fact from "not
+    # reachable", and it must not share its answer. A `Contract-Change: yes` is being claimed against
+    # an epic that has no locked surface at all, so there is nothing the claim could be true of.
+    #
+    # This is the steady state of the short lanes (E40): `chore` and `spike` carry no architecture
+    # step, so `contract.md` and `contract-lock.json` never exist on them. Deferring here meant every
+    # short-lane epic could move the shared cross-repo surface forever, with a note that reads like a
+    # pass. The guard used to be prose in the authoring skills; this is the gate.
+    #
+    # Narrow on purpose, and the guard is the EPIC'S LEDGER DIRECTORY, not the product path — because
+    # `resolve_product` ALWAYS returns some path and never verifies that the one it picked exists. (Its
+    # own two `-d` tests only choose BETWEEN the story-relative and repo-root joins; neither rejects a
+    # miss.) Requiring `epics/<epic>/.sdlc/` to exist is what separates "this epic is real and has no
+    # lock" from "nothing is checked out here". A CI job that does not check the
+    # product repo out still defers below, exactly as before — that case proves nothing either way,
+    # and failing it would break every setup that has always run this way.
+    # The escape hatch described at the top: with no lock upstream there is no agreed shape for a
+    # deletion to contradict, so REMOVING a slice is always allowed here. This is what keeps a
+    # short-lane story that should never have had a `contracts/` folder from being unfixable.
+    story_surface="$(printf '%s\n' "$surface" | grep -E "^specs/${story}/contracts/" || true)"
+    story_deleted="$(printf '%s\n' "$deleted" | grep -E "^specs/${story}/contracts/" || true)"
+    if [ -n "$story_surface" ] && [ "$story_surface" = "$story_deleted" ]; then
+      echo "note [contract-check]: ${story} only REMOVES contract slice files and ${epic} has no lock —"
+      echo "  nothing upstream is being contradicted, so the removal is allowed."
+      continue
+    fi
+    echo "FAIL [contract-check]: Contract-Change claimed, but ${epic} has no contract lock at all."
+    echo "  Expected ${lock} — the epic's ledger directory is there and the lock file is not."
+    echo "  Three ways to be here, with three different fixes:"
+    echo "   - a SHORT LANE (chore/spike): it has no architecture step and never locks a surface, so it"
+    echo "     carries no specs/<story>/contracts/ at all. DELETE the slice; a delete-only diff passes."
+    echo "     A real surface change belongs to a new epic on the classic route."
+    echo "   - a STUB / lightly-promoted brownfield epic: the feature was never documented, so there is"
+    echo "     nothing to lock yet. Run yad-backfill and promote it fully (which locks contract.md)."
+    echo "   - a CLASSIC epic that has not reached its architecture gate: author and lock contract.md"
+    echo "     first (yad-architecture Step 5)."
+    rc=1
+    continue
   else
     # Say so. A skipped fidelity check used to be indistinguishable from a passed one, which is how a
     # mis-resolved product-repo could turn a stale-pin FAIL into a silent PASS (issue #149).
@@ -156,7 +212,7 @@ $stories
 EOF
 
 if [ "$rc" != 0 ]; then
-  echo "FAIL [contract-check]: a changed slice pins a stale contract lock (see above) — the surface was not re-locked upstream for every story in this diff."
+  echo "FAIL [contract-check]: a changed slice pins a stale or absent contract lock (see above) — the surface was not re-locked upstream for every story in this diff."
   exit 1
 fi
 

package/skills/yad-checks/templates/checks/epic-open.sh

@@ -3,7 +3,7 @@
 # is `shipped`. A SEALED epic's artifacts are the final, approved description of shipped behaviour — so
 # new behaviour must NOT be added to it; it belongs in a NEW threaded change-epic whose re-authored
 # stories/test-cases describe the change. This gate FAILs any non-maintenance commit whose owning epic
-# is sealed, forcing the front half to stay current (staleness becomes unshippable).
+# is sealed, forcing Shape to stay current (staleness becomes unshippable).
 #
 # The owning epic lives in the PRODUCT repo (via specs/<story>/link.md `product-repo`). When it is not
 # reachable from CI, the seal cannot be read, so the commit PASSes with a note (degraded, fail-open here
@@ -53,7 +53,7 @@ fm_val() { awk -v k="$1" 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f &&
 # Same, for a link.md field. yad-spec writes link.md WITH frontmatter, but code repos still carry
 # pre-frontmatter ones that contract-check used to read with a whole-file scan — so fall back to that
 # rather than silently reading an empty value and skipping the check it guards. Deliberately separate
-# from fm_val: hub artifacts (epic.md, stories/*.md) stay bounded to their first block.
+# from fm_val: Product artifacts (epic.md, stories/*.md) stay bounded to their first block.
 link_val() {
   _v="$(fm_val "$1" "$2")"
   [ -n "$_v" ] || _v="$(sed -nE "s/^$1:[[:space:]]*(.*)\$/\1/p" "$2" 2>/dev/null | head -1 | tr -d '\r' | sed -E 's/[[:space:]]+$//')"
@@ -142,7 +142,7 @@ while IFS= read -r sha; do
   if epic_sealed "$ep_dir"; then
     echo "FAIL [epic-open]: ${short} ${task} targets SEALED epic ${epic} (all stories shipped)."
     echo "  -> New behaviour cannot mutate a shipped epic. Open a threaded change-epic with yad-change"
-    echo "     (kind: change|defect|hotfix, parent: ${epic}) and implement against ITS stories instead."
+    echo "     (type change|defect|hotfix, parent: ${epic}) and implement against ITS stories instead."
     rc=1
     continue
   fi

package/skills/yad-checks/templates/checks/install-deps.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Deterministic CI dependency installation selected by package.json#packageManager.
+set -euo pipefail
+
+YAD_CHECKS_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+readonly YAD_CHECKS_DIR
+# shellcheck source-path=SCRIPTDIR
+# shellcheck source=package-manager.sh
+source "$YAD_CHECKS_DIR/package-manager.sh"
+
+package_manager_spec="$(yad_package_manager_spec)"
+package_manager="$(yad_detect_package_manager "$package_manager_spec")"
+
+case "$package_manager" in
+  npm)
+    if [ ! -f "$YAD_NPM_LOCKFILE" ] && [ ! -f "$YAD_NPM_SHRINKWRAP" ]; then
+      echo "FAIL [install-deps]: npm requires package-lock.json or npm-shrinkwrap.json." >&2
+      exit 1
+    fi
+    if [[ "$package_manager_spec" == npm@* ]]; then
+      yad_require_corepack
+      corepack enable
+      yad_corepack_prepare "$package_manager_spec"
+      # npm's shim is not enabled by Corepack, so dispatch it explicitly through Corepack — the same
+      # `corepack npm` the gate uses for lint/build/test, so package.json#packageManager selects the
+      # npm version end to end instead of the Node image's ambient npm binary.
+      corepack npm ci
+    else
+      npm ci
+    fi
+    ;;
+  pnpm)
+    if [ ! -f "$YAD_PNPM_LOCKFILE" ]; then
+      echo "FAIL [install-deps]: pnpm requires pnpm-lock.yaml." >&2
+      exit 1
+    fi
+    if [[ "$package_manager_spec" != pnpm@* ]]; then
+      echo "FAIL [install-deps]: pnpm CI requires an exact package.json#packageManager value (for example pnpm@9.15.0)." >&2
+      exit 1
+    fi
+    yad_require_corepack
+    corepack enable
+    yad_corepack_prepare "$package_manager_spec"
+    pnpm install --frozen-lockfile
+    ;;
+esac

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

@@ -1,13 +1,26 @@
 #!/usr/bin/env bash
 # ledger-guard gate.
-# In BRIDGE mode the gate ledger is CI-owned: only the yad gate-sync bot may change the
+# In verified mode the gate ledger is CI-owned: only the yad gate-sync bot may change the
 # machine-written gate-state files. A commit on a review PR by anyone else that modifies them is
 # rejected — the human keeps the artifact, CI keeps the ledger. This makes "CI is the sole writer of
 # the ledger" a mechanical guarantee instead of a convention.
 #
 # Protected (gate-state, machine-written):
-#   epics/*/.sdlc/state.json, approvals.json, comments.json, hub-prs.json
+#   epics/*/.sdlc/state.json, approvals.json, comments.json, product-prs.json, hub-prs.json
+#   foundation/.sdlc/… and foundation/reviews/*.md — the same files for the Product level (E75), whose
+#   ledger lives in its own top-level folder. A copy of this script from before that release does NOT
+#   guard them; `yad doctor` says so on a verified Product that has a Foundation, and `yad update`
+#   refreshes this file.
+#
+# BOTH names of the PR ledger are guarded. It was renamed `hub-prs.json` -> `product-prs.json`, and
+# the engine writes both for one major so that a copy of THIS script which predates the rename still
+# finds the file it knows. Guarding only one name would leave the other open to a hand-edit on a
+# verified product — the exact thing this gate exists to refuse.
 #   epics/*/reviews/*.md
+#   .sdlc/index.json — the Product index (E19): derived from the ledgers above, and rebuilt by CI in the
+#   same commit that records a merge. Exactly that one path: the files beside it (product.json, hub.json,
+#   repos.json…) are a person's to edit, and a wider arm would refuse `yad mode` and `yad setup` commits.
+#   It is never a seed, so no carve-out applies to it.
 # NOT protected:
 #   epics/*/.sdlc/contract-lock.json — artifact-side: the architect locks the contract surface in
 #   `gate open`, so a human legitimately commits it alongside the architecture artifact.
@@ -20,21 +33,22 @@
 # distinguishes CI-generated commits. A spoofed-author commit that is not Verified is treated as a
 # human edit and rejected.
 #
-# Scope: enforced ONLY when the bridge is enabled — hub.json carries BOTH a `platform` and
-# `bridge_enabled` (or the legacy `bridge`) true, the same predicate `isBridge` (cli/gate.mjs) and
-# `hubActions` (cli/plan.mjs) apply. Without the bridge (file-only / non-bridge, or a platform-less
-# hub) humans legitimately write the ledger locally, so the gate is a no-op.
+# Scope: enforced ONLY when the ledger is verified — hub.json carries BOTH a `platform` and either
+# `ledger: "verified"` or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or the
+# legacy `bridge`) true. That is the same predicate `isVerifiedLedger` (cli/manifest.mjs) and
+# `productActions` (cli/plan.mjs) apply. With a local ledger — or a platform-less Product — humans
+# legitimately write the ledger themselves, so the gate is a no-op.
 #
 # Degradation: a base ref that cannot be resolved FAILs closed; no platform (cannot read the Verified
 # badge) WARNs and waives the signature half — the same stance verified-commits takes.
 set -euo pipefail
 
 # ---- bridge gate: only CI-owned ledgers are guarded -------------------------------------------
-# The predicate is BOTH a platform and the bridge flag, exactly as `isBridge` (cli/gate.mjs) and
-# `hubActions` (cli/plan.mjs) define it. Requiring the flag alone put this gate out of step with every
-# other bridge detector (issue #186): a hub carrying `bridge_enabled: true` with no `platform` would
+# The predicate is BOTH a platform and the verified ledger flag, exactly as `isVerifiedLedger` (`cli/manifest.mjs`) and
+# `productActions` (cli/plan.mjs) define it. Requiring the flag alone put this gate out of step with every
+# other ledger reader (issue #186): a Product carrying `bridge_enabled: true` with no `platform` would
 # have its human ledger commits rejected here while the CLI, reading the same file, called it
-# file-only and kept the LOCAL write path — no CI writer and no permitted human writer, so no gate
+# local and kept the LOCAL write path — no CI writer and no permitted human writer, so no gate
 # could advance. Reachable through a stale install (platform set, script wired, platform later
 # nulled), not through `yad setup`, which derives both from one value.
 #
@@ -44,8 +58,8 @@ set -euo pipefail
 #
 # Matched at the ROOT LEVEL only. The shared `default_branch` read below is depth-blind, and that is
 # survivable there — a false match yields a bogus branch name and the gate fails loudly. Here it is
-# not: a nested `"bridge": true` (say under `review`) would silently ENABLE this gate on a hub whose
-# `isBridge` is false, recreating the exact no-writer deadlock #186 is about, from the other side. So
+# not: a nested `"bridge": true` (say under `review`) would silently ENABLE this gate on a Product whose
+# `isVerifiedLedger` is false, recreating the exact no-writer deadlock #186 is about, from the other side. So
 # the nesting is stripped rather than ignored: peel the outermost braces, then delete innermost
 # objects/arrays until none remain, leaving only root-level pairs to match against. Not a JSON parser
 # — a value containing a literal brace would confuse it — but hub.json is machine-written and the
@@ -67,9 +81,37 @@ done
 # SIGPIPE-under-pipefail problem this avoids).
 hub_str() { sed -nE "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p" <<< "$HUB_ROOT"; }
 hub_true() { grep -Eq "\"$1\"[[:space:]]*:[[:space:]]*true" <<< "$HUB_ROOT"; }
+# Is the key present with a STRING value at all, empty included? `hub_str` cannot answer this: it
+# returns nothing both for a missing key and for an empty one.
+hub_has_str() { grep -Eq "\"$1\"[[:space:]]*:[[:space:]]*\"" <<< "$HUB_ROOT"; }
 
-if [ ! -f "$HUB" ] || [ -z "$(hub_str platform)" ] || { ! hub_true bridge_enabled && ! hub_true bridge; }; then
-  echo "PASS [ledger-guard]: bridge not enabled — the ledger is locally owned, nothing to guard."
+# READ ORDER, identical to `isVerifiedLedger` (cli/manifest.mjs) — the two must never disagree:
+#   1. `ledger`, if hub.json carries it — shape 2 and later. "verified" and nothing else.
+#   2. otherwise the old booleans `bridge_enabled` (canonical) or `bridge` (older still).
+# A platform is required either way, for the reason in the header.
+#
+# Step 2 is NOT dead weight. This script is committed inside the user's repo and refreshed by
+# `yad update`, which is a separate act from `yad migrate` — so an un-migrated hub.json (no `ledger`
+# key at all) will be read by this version of the script, and it has to keep saying "verified".
+# cli/test-checks.mjs runs a table of hub.json variants through this script AND through the JS
+# reader and asserts they agree on every row.
+# Written as if/else rather than `cmd; verified=$?`: under the `set -e` above, a bare failing test
+# would EXIT the script instead of recording a false — and exiting mid-guard is indistinguishable
+# from passing, so the gate would silently stop guarding.
+# PRESENCE of the key decides which branch runs, not whether its value is non-empty. `"ledger": ""`
+# is a present key with a string value: the JS reader stops there and answers "local", so this must
+# too. Testing `-n` instead sent an empty value down to the old booleans and the two readers gave
+# OPPOSITE answers — the guard rejecting human writes while the CLI kept the local path open, which
+# is the no-writer deadlock of #186 reached from a third direction.
+verified=no
+if hub_has_str ledger; then
+  if [ "$(hub_str ledger)" = "verified" ]; then verified=yes; fi
+elif hub_true bridge_enabled || hub_true bridge; then
+  verified=yes
+fi
+
+if [ ! -f "$HUB" ] || [ -z "$(hub_str platform)" ] || [ "$verified" != yes ]; then
+  echo "PASS [ledger-guard]: the ledger is locally owned (ledger: local) — nothing to guard."
   exit 0
 fi
 
@@ -159,7 +201,7 @@ trusted_bot() {
 # A brand-new epic's ledger has no CI author. `gate ci` only ADVANCES an existing chain — it bails on
 # a missing state.json ("the review branch is cut from the default branch, so it should carry it") and
 # writes only at merge, on the default branch — and the engine itself reads a missing state.json as
-# "not seeded yet". `gate open` writes nothing in bridge mode, and `checkpoint` stages back-half
+# "not seeded yet". `gate open` writes nothing in verified mode, and `checkpoint` stages Build
 # ledgers only. So the seed the authoring skills write (yad-epic / yad-change / yad-analysis /
 # yad-discovery / yad-stub) can reach the trunk ONLY through the first review PR/MR — the one place
 # this gate runs. Guarding it there makes the documented flow unshippable on a protected trunk, so an
@@ -200,15 +242,32 @@ is_seeding() {                      # $1 = epic slug; 0 when that epic has no le
           _s="${_p#epics/}"; _s="${_s%%/*}"
           base_slugs[${#base_slugs[@]}]="$(fold "$_s")"
           ;;
+        # The Product level (E75) has ONE ledger, in `foundation/`, under the fixed id EP-foundation.
+        foundation/.sdlc/state.json)
+          base_slugs[${#base_slugs[@]}]="ep-foundation"
+          ;;
       esac
-    done < <(git -c core.quotePath=false ls-tree -r --name-only -z "${BASE}" -- epics 2>/dev/null || true)
+    done < <(git -c core.quotePath=false ls-tree -r --name-only -z "${BASE}" -- epics foundation 2>/dev/null || true)
+    # A product has ONE product level. When its OLD spelling (epics/EP-discovery) is already on BASE, a
+    # Foundation ledger is not a new product level being created — it is a second one replacing a
+    # CI-owned ledger, and on a verified Product no CI path writes one. So it counts as seeded, and a
+    # human commit adding it is a mutation like any other.
+    if in_list "ep-discovery" "${base_slugs[@]}"; then
+      base_slugs[${#base_slugs[@]}]="ep-foundation"
+    fi
+    # …and the mirror: with a Foundation on BASE, a fresh epics/EP-discovery ledger is a second product
+    # level too, not a new epic.
+    if in_list "ep-foundation" "${base_slugs[@]}"; then
+      base_slugs[${#base_slugs[@]}]="ep-discovery"
+    fi
     base_slugs_loaded=1
   fi
   _f="$(fold "$1")"
   in_list "$_f" "${base_slugs[@]}"  && return 1
   in_list "$_f" "${noted_slugs[@]}" && return 0
   noted_slugs[${#noted_slugs[@]}]="$_f"
-  echo "note [ledger-guard]: epics/$1 has no ledger on ${BASE} — new epic, its seed is exempt (creation, not mutation)."
+  if [ "$_f" = "ep-foundation" ]; then _where="foundation"; else _where="epics/$1"; fi
+  echo "note [ledger-guard]: ${_where} has no ledger on ${BASE} — new epic, its seed is exempt (creation, not mutation)."
   return 0
 }
 
@@ -221,13 +280,30 @@ for sha in $commits; do
   while IFS= read -r -d '' f; do
     [ -n "$f" ] || continue
     case "$f" in
+      .sdlc/index.json)                    # the Product index (E19) — derived, CI-written, never a seed
+        touches_ledger=1
+        echo "  ${sha} (author $(git show -s --format='%an' "$sha")) → $f"
+        ;;
       epics/*/.sdlc/contract-lock.json) ;; # artifact-side — allowed
-      epics/*/.sdlc/state.json|epics/*/.sdlc/approvals.json|epics/*/.sdlc/comments.json|epics/*/.sdlc/hub-prs.json|epics/*/reviews/*.md)
+      epics/*/.sdlc/state.json|epics/*/.sdlc/approvals.json|epics/*/.sdlc/comments.json|epics/*/.sdlc/product-prs.json|epics/*/.sdlc/hub-prs.json|epics/*/reviews/*.md)
         _slug="${f#epics/}"; _slug="${_slug%%/*}"
         is_seeding "$_slug" && continue      # a new epic's seed — not a mutation of a CI-owned ledger
         touches_ledger=1
         echo "  ${sha} (author $(git show -s --format='%an' "$sha")) → $f"
         ;;
+      # The Foundation's ledger (E75) — the same files, in the Product level's own folder, under the fixed
+      # id EP-foundation. Matched on the path BELOW `foundation/` with a leading `/` put back, so the
+      # same `*/.sdlc/<file>` test covers the ledger itself and a nested copy (the epic arms' `*` spans
+      # `/` too) without also catching a section file that merely ends in `.sdlc` or `reviews`.
+      foundation/*)
+        case "/${f#foundation/}" in
+          */.sdlc/state.json|*/.sdlc/approvals.json|*/.sdlc/comments.json|*/.sdlc/product-prs.json|*/.sdlc/hub-prs.json|*/reviews/*.md)
+            is_seeding "EP-foundation" && continue
+            touches_ledger=1
+            echo "  ${sha} (author $(git show -s --format='%an' "$sha")) → $f"
+            ;;
+        esac
+        ;;
     esac
   done < <(git -c core.quotePath=false diff-tree --no-commit-id --name-only -r -z "$sha")
   if [ "$touches_ledger" = 1 ] && ! trusted_bot "$sha"; then

package/skills/yad-checks/templates/checks/lineage-check.sh

@@ -52,7 +52,7 @@ fm_val() { awk -v k="$1" 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f &&
 # Same, for a link.md field. yad-spec writes link.md WITH frontmatter, but code repos still carry
 # pre-frontmatter ones that contract-check used to read with a whole-file scan — so fall back to that
 # rather than silently reading an empty value and skipping the check it guards. Deliberately separate
-# from fm_val: hub artifacts (epic.md, stories/*.md) stay bounded to their first block.
+# from fm_val: Product artifacts (epic.md, stories/*.md) stay bounded to their first block.
 link_val() {
   _v="$(fm_val "$1" "$2")"
   [ -n "$_v" ] || _v="$(sed -nE "s/^$1:[[:space:]]*(.*)\$/\1/p" "$2" 2>/dev/null | head -1 | tr -d '\r' | sed -E 's/[[:space:]]+$//')"
@@ -113,7 +113,7 @@ while IFS= read -r sha; do
   fi
   prod="$(resolve_product "$product_rel" "$story")"
   epicmd="${prod}/epics/${epic}/epic.md"
-  # Defer ONLY when the product checkout itself is unreachable. A reachable hub whose epic is missing is
+  # Defer ONLY when the product checkout itself is unreachable. A reachable Product whose epic is missing is
   # an orphaned story link — FAIL, do not pass it off as "not reachable".
   if [ -z "$product_rel" ] || [ ! -d "$prod" ]; then
     echo "PASS [lineage-check]: ${short} ${task} -> epic ${epic} (product repo not reachable — lineage check deferred)."
@@ -124,25 +124,39 @@ while IFS= read -r sha; do
     rc=1
     continue
   fi
-  kind="$(fm_val kind "$epicmd")"
-  [ -z "$kind" ] && kind="feature"
-  if [ "$kind" = "feature" ]; then
-    echo "PASS [lineage-check]: ${short} ${task} -> ${epic} (genesis feature epic)."
+  # The work-item TYPE. Two names are alive: `kind:` is the original and is still the one that
+  # counts; `type:` is the name from shape 5 on, written beside it. READ ORDER IS OLD FIRST, and it
+  # is the same order `workItemType` uses in cli/epic-state.mjs — cli/test-checks.mjs runs a table of
+  # frontmatter through both and asserts they agree, because two readers is two ways to drift.
+  # Absent from both means `feature`: an epic authored before types existed is its own thread root.
+  wtype="$(fm_val kind "$epicmd")"
+  [ -z "$wtype" ] && wtype="$(fm_val type "$epicmd")"
+  [ -z "$wtype" ] && wtype="feature"
+  # `feature` and `chore` may stand alone. Upkeep — a dependency bump, a CI move — usually has no
+  # feature to hang off, and an invented parent is worse than none: every thread rollup walks
+  # `parent:` and would file the upkeep under a feature it has nothing to do with.
+  #
+  # NOTE the asymmetry, which `feature` has always had: this PASSES before it looks at `parent:` at
+  # all, so a genesis type that DOES declare a dangling parent is not checked here. `yad doctor`
+  # catches that one (threadChecks skips only the parent-LESS case), so it is covered — just not by
+  # this gate.
+  if [ "$wtype" = "feature" ] || [ "$wtype" = "chore" ]; then
+    echo "PASS [lineage-check]: ${short} ${task} -> ${epic} (genesis ${wtype} epic)."
     continue
   fi
   # A change/defect/hotfix epic MUST thread to a real parent.
   parent="$(fm_val parent "$epicmd")"
   if [ -z "$parent" ]; then
-    echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} is kind:${kind} but declares no 'parent:' — a change-epic must thread to its predecessor."
+    echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} is type:${wtype} but declares no 'parent:' — a change-epic must thread to its predecessor."
     rc=1
     continue
   fi
   if [ ! -f "${prod}/epics/${parent}/epic.md" ]; then
-    echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} threads to '${parent}', but epics/${parent}/ does not exist in the hub (orphan thread)."
+    echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} threads to '${parent}', but epics/${parent}/ does not exist in the Product (orphan thread)."
     rc=1
     continue
   fi
-  echo "PASS [lineage-check]: ${short} ${task} -> ${epic} (kind:${kind} threaded to ${parent})."
+  echo "PASS [lineage-check]: ${short} ${task} -> ${epic} (type:${wtype} threaded to ${parent})."
 done <<EOF
 $commits
 EOF