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

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

@@ -7,6 +7,11 @@
 # (link.md's pinned hash must match the product lock). Otherwise FAIL and route back to the
 # architecture gate. Normal implementation that only CONSUMES the contract passes untouched.
 set -euo pipefail
+# Bytes, not characters (E114). The changed list below carries raw path bytes, and a path that is not
+# valid UTF-8 read under a UTF-8 locale is one GNU grep and sed may skip or leave unmatched — one such
+# file in a diff would hide every other path from the patterns (Linux CI). On macOS, `tr` and `sed` stop
+# on it with "Illegal byte sequence" instead, so the gate fails with a message that names nothing.
+export LC_ALL=C
 
 # --- shared base resolution (byte-identical across the gates; they are standalone by design, so it
 # --- is duplicated, not sourced) ---
@@ -41,14 +46,89 @@ if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
 fi
 RANGE="${BASE}..HEAD"
 
-# core.quotePath=false: with the default ON, git wraps any path holding a non-ASCII byte in quotes
-# and octal-escapes it, so a slice like specs/EP-démo-S01/contracts/api.md never matches the pattern
-# below — the surface change would be invisible to the gate it exists to stop.
-changed="$(git -c core.quotePath=false diff --name-only "$RANGE")"
-surface="$(printf '%s\n' "$changed" | grep -E '^specs/[^/]+/contracts/' || true)"
+# No symlink and no submodule anywhere under specs/ (E115). The gate reads PATHS: a link lets the
+# content live somewhere the paths below never name. A symlink at `specs`, `specs/<story>` or
+# `specs/<story>/contracts` hid the slice from every rule here, and so did every later edit to the
+# link's target; a symlinked slice file was seen once, when added, and never again. A link.md behind a
+# link redirects the lock pin the fidelity check reads. yad-spec writes real files, so nothing
+# legitimate lives there as a link.
+#
+# Read from the TREE at HEAD, not from the diff, and before the "no surface" PASS below: a link merged
+# before this check existed fails every PR until one PR removes it — no diff would ever show it again.
+# 120000 is a symlink, 160000 a submodule; `-r` lists `specs` itself when `specs` is the link.
+#
+# The WHOLE tree, from the repo root (--full-tree), matched without case: on macOS and Windows `Specs/`
+# IS `specs/`, and git's path filter matches exact bytes only (`:(icase)` is refused by ls-tree). So a
+# link under `Specs/` got past a `-- specs` read, and a plain file at `Specs/<story>/contracts/…` was
+# never on the surface below, which is spelled in lowercase. A top folder spelled any other way than
+# `specs` is refused too, once, by its own name. The name printed is everything after the first tab.
+# `tolower` under LC_ALL=C folds ASCII only, so the one other letter the file systems fold into "specs"
+# is mapped by hand: `ſ` (long s, U+017F, bytes 305 277) — APFS reads `ſpecs/` as `specs/`. That is
+# `fold` below.
+#
+# The same holds one and two folders down (review 3): `specs/<story>/Contracts/` IS `contracts/` on a
+# Mac, and `specs/EP-x-S01/` and `specs/ep-x-s01/` are one folder there, while every rule below reads
+# exact bytes. So a `contracts` spelled any other way is refused, and so is a second spelling of a
+# story folder — each once, by name. So is a FILE named `specs`, where the folder has to go. `fold`
+# knows ASCII case and the long s only: `EP-démo` beside `EP-DÉMO` (or an NFC/NFD twin) is not caught.
+# That costs a skipped lock check at most — the surface grep takes any story spelling — and refusing
+# every non-ASCII story name would refuse real repos.
+links="$(git ls-tree -r -z --full-tree HEAD | tr '\0' '\n' | awk '
+  function fold(x) { x = tolower(x); gsub(/\305\277/, "s", x); return x }
+  function once(k, msg) { if (!(k in said)) { said[k] = 1; print "  " msg } }
+  { t = index($0, "\t"); p = (t ? substr($0, t + 1) : $0); m = (t ? substr($0, 1, t - 1) : ""); lp = fold(p) }
+  lp !~ /^specs(\/|$)/ { next }
+  m ~ /^120000 / { print "  " p " (symlink)"; next }
+  m ~ /^160000 / { print "  " p " (submodule)"; next }
+  p !~ /^specs(\/|$)/ { top = p; sub(/\/.*/, "", top); once(top, (top == p ? top " (a file" : top "/ (a folder") " spelled other than specs — the same name on macOS and Windows)"); next }
+  p == "specs" { print "  specs (a file, where the specs/ folder goes)"; next }
+  { n = split(p, c, "/"); fs = fold(c[2]) }
+  (fs in story) && story[fs] != c[2] { once("s/" c[2], "specs/" story[fs] (n == 2 ? " and specs/" c[2] " (one file" : "/ and specs/" c[2] "/ (one folder") " on macOS and Windows)") }
+  !(fs in story) { story[fs] = c[2] }
+  n >= 3 && c[3] != "contracts" && fold(c[3]) == "contracts" { once("c/" c[2] "/" c[3], "specs/" c[2] "/" c[3] (n == 3 ? " (a file" : "/ (a folder") " spelled other than contracts — the same name on macOS and Windows)") }
+')" || { echo "FAIL [contract-check]: could not read the tree at HEAD — the links under specs/ cannot be checked."; exit 1; }
+if [ -n "$links" ]; then
+  echo "FAIL [contract-check]: specs/ holds a symlink, a submodule or a second spelling — this gate cannot see what it points at:"
+  printf '%s\n' "$links"
+  echo "  -> replace each link with the real files (yad-spec writes real files), and keep ONE spelling"
+  echo "     of each folder: specs/, specs/<story>/, specs/<story>/contracts/. Until then every PR in this"
+  echo "     repo fails here, because the contract surface cannot be checked. Removing a link or merging"
+  echo "     a spelling is itself a change to specs/: under contracts/ it needs 'Contract-Change: yes'."
+  exit 1
+fi
+
+# How the changed list is built, and why each flag is there (E114):
+#   --no-renames  a rename is listed by BOTH paths, as a delete and an add. Without it git names a
+#                 rename by its NEW path only, so `git mv specs/S1/contracts/api.md docs/api.md`
+#                 took the slice off the surface and the gate never saw it — no trailer needed.
+#   -z | tr       NUL-separated, so git never quotes a path. By default git wraps a path holding a
+#                 non-ASCII byte in quotes and octal-escapes it, and it still quotes one holding a `"`
+#                 or a tab with core.quotePath off — either way a slice like
+#                 specs/EP-démo-S01/contracts/api.md never matched the pattern below.
+# Both lists (this one and `deleted` below) are built the SAME way: the no-lock escape hatch compares
+# them line for line.
+changed="$(git diff --no-renames --name-only -z "$RANGE" | tr '\0' '\n')"
+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).
+# --no-renames matters here too: a slice MOVED out of contracts/ is a delete of the old path, and
+# without it git reports an `R`, which --diff-filter=D never matches — the hatch would refuse the move.
+deleted="$(git diff --no-renames --diff-filter=D --name-only -z "$RANGE" | tr '\0' '\n' | grep -E '^specs/[^/]+/contracts(/|$)' || true)"
 
 if [ -z "$surface" ]; then
-  echo "PASS [contract-check]: diff does not touch the contract surface (specs/*/contracts/**)."
+  echo "PASS [contract-check]: diff does not touch the contract surface (specs/*/contracts and everything under it)."
   exit 0
 fi
 
@@ -59,6 +139,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 +156,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:]]+$//')"
@@ -105,7 +187,7 @@ resolve_product() {
 # link.md deferred the whole check before the stale one was ever read (issue #161). Failures are
 # AGGREGATED — every story reports, so one clean-or-deferred story never masks another's stale pin
 # (the same rule spec-link applies per commit).
-stories="$(printf '%s\n' "$surface" | sed -E 's#^specs/([^/]+)/contracts/.*#\1#' | sort -u)"
+stories="$(printf '%s\n' "$surface" | sed -E 's#^specs/([^/]+)/contracts(/.*)?$#\1#' | sort -u)"
 rc=0
 while IFS= read -r story; do
   [ -z "$story" ] && continue
@@ -146,6 +228,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 +277,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

@@ -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/ledger-guard.sh

@@ -6,8 +6,21 @@
 # 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.
@@ -23,7 +36,7 @@
 # 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
-# `hubActions` (cli/plan.mjs) apply. With a local ledger — or a platform-less hub — humans
+# `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
@@ -32,8 +45,8 @@ set -euo pipefail
 
 # ---- bridge gate: only CI-owned ledgers are guarded -------------------------------------------
 # The predicate is BOTH a platform and the verified ledger flag, exactly as `isVerifiedLedger` (`cli/manifest.mjs`) and
-# `hubActions` (cli/plan.mjs) define it. Requiring the flag alone put this gate out of step with every
-# other ledger reader (issue #186): a hub carrying `bridge_enabled: true` with no `platform` would
+# `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
 # 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
@@ -45,7 +58,7 @@ 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
+# 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
@@ -229,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
 }
 
@@ -250,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

package/skills/yad-checks/templates/checks/reconcile-debt-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:]]+$//')"