yadflow 4.0.0-next.3 → 4.0.0

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

@@ -28,10 +28,12 @@
 #   seed rides the first review PR/MR; see the carve-out below. Mutation stays bot-only.
 #
 # A "bot commit" must be BOTH authored by the gate bot (name/email contains yad-gate-sync) AND
-# platform-VERIFIED — author/committer text alone is user-controlled and spoofable, so the platform
-# Verified signature (a key the contributor cannot forge under the bot identity) is what actually
-# distinguishes CI-generated commits. A spoofed-author commit that is not Verified is treated as a
-# human edit and rejected.
+# platform-VERIFIED. A spoofed-author commit that is not Verified is treated as a human edit and
+# rejected. Known gap: the Verified badge proves only that the COMMITTER signed with their own key, not
+# that the bot did, so a contributor who signs can still write the bot's name as the author. The
+# GitHub workflow therefore gives this job no token: the badge lookup fails and every bot-attributed
+# ledger commit is refused. On GitLab the project token reaches this job, so the gap is still open there
+# (see references/check-gates.md).
 #
 # 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
@@ -43,6 +45,30 @@
 # badge) WARNs and waives the signature half — the same stance verified-commits takes.
 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
+
 # ---- 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
 # `productActions` (cli/plan.mjs) define it. Requiring the flag alone put this gate out of step with every
@@ -68,22 +94,22 @@ set -euo pipefail
 # Flattened ONCE into a variable and matched with here-strings, never `tr … | grep -q`: under the
 # `pipefail` set above, `grep -q` exits at the first match and can SIGPIPE `tr`, which would make a
 # MATCHING pipeline report failure. Reading from a here-string has no upstream process to kill.
-HUB="${SDLC_HUB_CONFIG:-.sdlc/hub.json}"
-HUB_FLAT="$(tr -d '\n' < "$HUB" 2>/dev/null || true)"
-HUB_ROOT="${HUB_FLAT#*\{}"
-HUB_ROOT="${HUB_ROOT%\}*}"
+SETTINGS="$PRODUCT_CONFIG"
+SETTINGS_FLAT="$({ tr -d '\n' < "$SETTINGS"; } 2>/dev/null || true)"
+SETTINGS_ROOT="${SETTINGS_FLAT#*\{}"
+SETTINGS_ROOT="${SETTINGS_ROOT%\}*}"
 while :; do
-  _stripped="$(sed -E 's/\{[^{}]*\}//g; s/\[[^][]*\]//g' <<< "$HUB_ROOT")"
-  [ "$_stripped" = "$HUB_ROOT" ] && break
-  HUB_ROOT="$_stripped"
+  _stripped="$(sed -E 's/\{[^{}]*\}//g; s/\[[^][]*\]//g' <<< "$SETTINGS_ROOT")"
+  [ "$_stripped" = "$SETTINGS_ROOT" ] && break
+  SETTINGS_ROOT="$_stripped"
 done
 # One line in, so `sed` emits at most one line out — no `head` needed (which would re-introduce the
 # 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
+setting_str() { sed -nE "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p" <<< "$SETTINGS_ROOT"; }
+setting_true() { grep -Eq "\"$1\"[[:space:]]*:[[:space:]]*true" <<< "$SETTINGS_ROOT"; }
+# Is the key present with a STRING value at all, empty included? `setting_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"; }
+setting_has_str() { grep -Eq "\"$1\"[[:space:]]*:[[:space:]]*\"" <<< "$SETTINGS_ROOT"; }
 
 # 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.
@@ -104,13 +130,13 @@ hub_has_str() { grep -Eq "\"$1\"[[:space:]]*:[[:space:]]*\"" <<< "$HUB_ROOT"; }
 # 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
+if setting_has_str ledger; then
+  if [ "$(setting_str ledger)" = "verified" ]; then verified=yes; fi
+elif setting_true bridge_enabled || setting_true bridge; then
   verified=yes
 fi
 
-if [ ! -f "$HUB" ] || [ -z "$(hub_str platform)" ] || [ "$verified" != yes ]; then
+if [ ! -f "$SETTINGS" ] || [ -z "$(setting_str platform)" ] || [ "$verified" != yes ]; then
   echo "PASS [ledger-guard]: the ledger is locally owned (ledger: local) — nothing to guard."
   exit 0
 fi
@@ -119,7 +145,7 @@ fi
 # --- 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
@@ -128,7 +154,7 @@ fi
 # 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
@@ -197,6 +223,15 @@ trusted_bot() {
   signature_verified "$1"
 }
 
+# Text a commit's author chose — a name, a path, a Ledger-Override reason — is printed into the CI log.
+# The GitHub runner ends a log line at a lone carriage return too, so every control character (CR, ESC,
+# …) becomes a space first; otherwise `\r::error::…` inside a path or a reason would start a line
+# GitHub Actions reads as a workflow command.
+# `printable` keeps newlines, for a list read line by line; `oneline` is for one value (a name, a path),
+# where a newline would start a line of its own too.
+printable() { LC_ALL=C tr '\000-\011\013-\037\177' ' '; }
+oneline() { printf '%s' "$1" | LC_ALL=C tr '\000-\037\177' ' '; }
+
 # ---- seeding carve-out: creation is not mutation (#162) ---------------------------------------
 # 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
@@ -266,12 +301,20 @@ is_seeding() {                      # $1 = epic slug; 0 when that epic has no le
   in_list "$_f" "${base_slugs[@]}"  && return 1
   in_list "$_f" "${noted_slugs[@]}" && return 0
   noted_slugs[${#noted_slugs[@]}]="$_f"
-  if [ "$_f" = "ep-foundation" ]; then _where="foundation"; else _where="epics/$1"; fi
+  if [ "$_f" = "ep-foundation" ]; then _where="foundation"; else _where="epics/$(oneline "$1")"; fi
   echo "note [ledger-guard]: ${_where} has no ledger on ${BASE} — new epic, its seed is exempt (creation, not mutation)."
   return 0
 }
 
 violations=0
+# E49: `yad commit --manual --reason` records why a person committed past the local ledger hook, as a
+# `Ledger-Override:` trailer. Anyone can type a trailer, so it changes NOTHING about the verdict — the
+# failing commit still fails. The reason is quoted under the FAIL so the reviewer sees why it was done.
+# Every quoted line goes through `printable` (above) and starts with the commit's sha: a reason is the
+# commit author's text, and a line whose first non-blank characters were `::` would be read by GitHub
+# Actions as a workflow command. Indenting alone would not stop that — the runner skips leading spaces —
+# so every line that prints author text starts with text of ours (the sha, `note [ledger-guard]:`).
+overrides=()
 for sha in $commits; do
   touches_ledger=0
   # quotePath=false + -z on both git reads: a path git chose to escape ("epics/EP-caf\303\251/…") and a
@@ -282,14 +325,14 @@ for sha in $commits; do
     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"
+        echo "  ${sha} (author $(oneline "$(git show -s --format='%an' "$sha")")) → $(oneline "$f")"
         ;;
       epics/*/.sdlc/contract-lock.json) ;; # artifact-side — allowed
       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"
+        echo "  ${sha} (author $(oneline "$(git show -s --format='%an' "$sha")")) → $(oneline "$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
@@ -300,7 +343,7 @@ for sha in $commits; do
           */.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"
+            echo "  ${sha} (author $(oneline "$(git show -s --format='%an' "$sha")")) → $(oneline "$f")"
             ;;
         esac
         ;;
@@ -308,11 +351,18 @@ for sha in $commits; do
   done < <(git -c core.quotePath=false diff-tree --no-commit-id --name-only -r -z "$sha")
   if [ "$touches_ledger" = 1 ] && ! trusted_bot "$sha"; then
     violations=$((violations + 1))
+    while IFS= read -r _why; do
+      [ -n "$_why" ] && overrides[${#overrides[@]}]="  ${sha} Ledger-Override: ${_why}"
+    done < <(git show -s --format='%(trailers:key=Ledger-Override,valueonly,unfold)' "$sha" 2>/dev/null | printable || true)
   fi
 done
 
 if [ "$violations" -gt 0 ]; then
   echo "FAIL [ledger-guard]: ${violations} commit(s) change CI-owned gate files without a verified gate-bot signature. The ledger is CI-owned — let CI sync the gate; do not commit .sdlc/*.json or reviews/*.md yourself."
+  if [ "${#overrides[@]}" -gt 0 ]; then
+    echo "note [ledger-guard]: these commits carry a Ledger-Override trailer — the reason a person gave for committing past the local hook (\`yad commit --manual\` writes it). It is quoted for the reviewer and does not change the verdict:"
+    printf '%s\n' "${overrides[@]}"
+  fi
   # An epic's seed is exempt only while its ledger is off the base ref. Once the first review PR merges
   # (squashed or rebased, so the SHAs differ), those same seed commits still sitting on a sibling
   # authoring branch read as mutations — the author did nothing wrong and the remedy is a rebase, so