.github/scripts/vendored-check.sh

@@ -85,11 +85,22 @@ mapfile -t manifest < <(grep -v '^[[:space:]]*$' "$manifest_file" || true)
 # work tree root. Fixture trees are plain directories, and asserting
 # tracked-ness against an enclosing repository would be asserting about the
 # wrong tree.
+#
+# When it cannot bind, SAY SO. This guard's whole argument is that a silent
+# miss is worse than a loud one, and a guard that quietly stops asserting one
+# of its four properties is exactly that shape — so the skip is announced on
+# every run, green or red, rather than inferred from the absence of a
+# refusal (#251 round 1).
 tracked_check=no
+tracked_note="tracked-ness NOT asserted: $tree is not a git work tree root, so
+  'is this file in the tag's tree' cannot be answered about THIS tree. The
+  other three manifest assertions (regular file, non-empty, no
+  symlink/dir/escape) still bind."
 if command -v git >/dev/null 2>&1; then
   toplevel="$(git -C "$tree" rev-parse --show-toplevel 2>/dev/null || true)"
   if [ -n "$toplevel" ] && [ "$toplevel" = "$(cd "$tree" && pwd -P)" ]; then
     tracked_check=yes
+    tracked_note=""
   fi
 fi
 
@@ -211,11 +222,13 @@ if [ "${#problems[@]}" -gt 0 ]; then
     printf 'vendored-check: %d problem(s) — docs/VENDORED.txt and the tree disagree.\n\n' \
       "${#problems[@]}"
     printf '%s\n\n' "${problems[@]}"
+    [ -z "$tracked_note" ] || printf 'vendored-check: %s\n' "$tracked_note"
   } >&2
   exit 1
 fi
 
 printf 'vendored-check: %d manifest entries resolve; %d root docs vendored, %d exempt.\n' \
   "${#manifest[@]}" "${#vendored[@]}" "${#exempted[@]}"
+[ -z "$tracked_note" ] || printf 'vendored-check: %s\n' "$tracked_note"
 [ "${#vendored[@]}" -eq 0 ] || printf '  vendored: %s\n' "${vendored[@]}"
 [ "${#exempted[@]}" -eq 0 ] || printf '  exempt:   %s\n' "${exempted[@]}"

docs/CONSUMERS.md

@@ -603,9 +603,10 @@ copying it ahead of their pinned doctrine set.
 Anything on the consumer's side that needs to know *which* documents are
 vendored — a re-vendor script, a `docs-sync` equivalent, the task list of a
 conversion issue — reads **the pin's `docs/VENDORED.txt`** and never names
-the files itself. The manifest is available at the pinned ref from `0.5.0`
+the files itself. The manifest is available at the pinned ref from `0.1.0`
-and later — it shipped with `actions/docs-sync` itself (ceremony#19) — and
+and later — it shipped with `actions/docs-sync` itself (ceremony#19), in the
-it is one path per line, relative to ceremony's root, blank lines ignored:
+same commit, and that tool has read it rather than a list since — and it is
+one path per line, relative to ceremony's root, blank lines ignored:
 
 ```sh
 # the vendored doc set at the ref this repo is pinned to

test/vendored.test.sh

@@ -199,6 +199,21 @@ git -C "$TMP/untracked" add docs/VENDORED.txt AGENTS.md
 check "a git tree with an untracked manifest entry reds" 1 "names 'RULES.md', which is not TRACKED" \
   run_check untracked
 
+# ...and where it cannot bind, the skip ANNOUNCES ITSELF rather than being
+# inferred from the absence of a refusal (#251 round 1). A guard that quietly
+# stops asserting one of its four properties is the silent miss this whole
+# script argues against, so the degradation is visible on both output paths.
+check "a non-git tree says tracked-ness was not asserted" 0 "tracked-ness NOT asserted" \
+  run_check ok
+check "...and says it on the red path too, beside the refusals" 1 "tracked-ness NOT asserted" \
+  run_check newdoc
+
+# The converse, so the note is not simply always printed: where the tree IS a
+# git work tree root the assertion bound, and nothing is announced.
+no_skip_note() { ! run_check tracked 2>&1 | grep -qF "tracked-ness NOT asserted"; }
+check "a git work tree root announces no skip — the assertion bound" 0 "" \
+  no_skip_note
+
 # --- the real tree -----------------------------------------------------------
 
 check "this tree, unmodified, is green" 0 "manifest entries resolve" bash "$CHECK" "$ROOT"