A declared visibility answers the shim, and a forge's silence says which silence it was

docs/REFERENCE.md

@@ -465,6 +465,23 @@ checkers down exactly where the lookup failed. That is exit `2` before the
 command runs, and `unresolved = "run"` on the `[[shim]]` table is the opt-out —
 see [the shims](#uphold-shim--the-shims).
 
+The rows above are what the forge said, and the shim reaches them only where it
+had to ask at all. A repository that declares its own `visibility` in its policy
+file has answered the question already, so `public-target` reads the declaration
+and asks nobody — `public` puts the checks in scope, `private` and `internal`
+stand them down, and no `gh` runs. That declaration speaks for this repository
+and for no other, so it is read for one destination only: the one the shim took
+from `origin` because nothing on the command line named another. A `gh -R
+owner/repo` goes to the forge exactly as it always did, and it does so **even
+where the name it carries is this repository's own** — a typed `owner/repo`
+has no host in it, so under a `--hostname` or a `GH_HOST` the same two names
+are a different forge's repository with its own visibility, and two matching
+path segments cannot tell the two apart. So the `2` above is still the answer
+for a named destination the forge could not be asked about, and for a repository
+that declares nothing; what is bought offline is the case the cost was actually
+in — the push that names nothing and means `origin`, which no longer needs an
+authenticated `gh` to be told what the policy already said.
+
 So **`gh` must be authenticated wherever these rules run**, CI included. In a
 GitHub Actions job that means `GH_TOKEN: ${{ github.token }}`; the job token
 reads this repository and public ones and answers `404` for everything else,
@@ -1161,7 +1178,7 @@ stamped on it, the range about to be pushed.
 | `no-merge-commit` | a commit finishing a merge or a squash merge |
 | `no-stale-hook-pins` | a pin left behind its upstream, or naming no ref — in `.pre-commit-config.yaml` **and** lefthook `remotes:`, at any depth in the tree; a pin it **could not check** is exit `2` |
 | `no-hand-copied-base-rule` | a rule this policy writes out by hand under an id a bundled set already ships, from a set it does not inherit. Reads the **policy**, not the tree. At `pre-commit` only what the change adds; at `manual` the whole sweep |
-| `no-stale-visibility` | a declared `private` the forge no longer serves. Reads the **declaration** and the forge, not the tree; a forge that did not answer is exit `2` and never "confirmed private" |
+| `no-stale-visibility` | a declared `private` the forge no longer serves. Reads the **declaration** and the forge, not the tree; a forge that did not answer is exit `2` and never "confirmed private", and it says which silence it met — a 404 reads differently from a rate limit |
 
 Declared like any other rule, in the same file and the same id namespace.
 **`git.hooks` is the whole registration.**
@@ -1504,8 +1521,27 @@ nested form is the enum's own spelling; the flatter one this page used to show
 never parsed.) `collect = "git-refs"` replaces the argv walk for `git`, whose
 published text is positional.
 
-**A scope that could not be evaluated is not a scope that said no.**
-`public-target` is the one predicate that asks somebody else, and `gh`
+**`public-target` asks this repository before it asks anybody else.** The
+policy's own top-level `visibility` is a statement of the fact the predicate
+needs, so where there is one it settles the question offline: `public` is in
+scope, `private` and `internal` are out of it, and nothing is spawned. The
+narrowing that makes reading it safe is that a declaration is about ONE
+repository, and the only destination this seam can be sure of is the one it
+derived itself. So the declaration is read where a `target_flags` value is
+absent — where the destination came from `origin` — and nowhere else. A named
+destination goes to the forge whatever it names: `gh -R other/repo` obviously,
+and `gh -R this-owner/this-repo` too, because the name carries no host and
+`--hostname` and `GH_HOST` both make `owner/repo` a different repository on a
+different forge. A tree whose `origin` cannot be read has no destination for a
+declaration to be about, and a policy that declares nothing changes nothing.
+The guard seam does the same thing one step less strictly (see
+`guard::names::target_is_public`), and the difference is deliberate: a guard
+reads text belonging to this repository, while a shim stands in front of a
+command that may be publishing somewhere else entirely.
+
+**A scope that could not be evaluated is not a scope that said no.** Where the
+question does reach a forge, `public-target` is the one predicate that asks
+somebody else, and `gh`
 unauthenticated, a rate limit, no network, or a repository with no `origin` all
 answer nothing. That was read as "out of scope", which stood every checker
 behind the table down — including `prevent-unowned-target`, whose own contract
@@ -1518,6 +1554,31 @@ reach `public-target` — neither the table's own `scope` nor the `command.scope
 of any rule naming the command — because a parameter nothing reads is
 configuration that looks like it works.
 
+**A silence is told apart from the other silences.** "The forge did not say" was
+one sentence for four different situations, and the one thing the reader needed
+in order to act was the one thing it left out: a 404, an unauthenticated `gh`, a
+rate limit and a `gh` that is not installed are four instructions, not one. So a
+failed forge call is classified once — in `shim::Silence`, which the shim seam,
+`no-stale-visibility` and `prevent-public-push` all read, because three
+classifiers would be free to disagree about one exit code and only one of them
+could be right — and the refusal carries the cause:
+
+```text
+uphold shim: the forge did not say whether acme/widget is public, so whether the
+`public-target` checks apply here could not be established. The forge is
+rate-limiting this client; the budget resets in about 15 minutes. This is not an
+answer about the repository -- it is the same silence for a public one and a
+private one.
+```
+
+The reset time is the one question this tool asks in reply to a failure, and it
+asks the one endpoint GitHub exempts from the limit it is reporting, so the ask
+cannot deepen the hole it is describing. **None of this changes a verdict.**
+Every one of these is still exit `2`, still not a pass, and still not a cached
+answer — a wait somebody can sit out is worth naming precisely because the
+alternative on offer is `UPHOLD_ALLOW`, and a reader who cannot tell a rate limit
+from a deleted repository reaches for the bypass either way.
+
 **An alias is expanded before the `match` list is consulted.** `match` names
 verbs literally, and every one of these commands lets a person rename one:
 `git -c alias.p=push p origin HEAD:refs/heads/x`, a persisted `[alias] p =
@@ -1671,9 +1732,12 @@ than the seam.
 
 The fourth is uphold getting out of its own way, and it is documented here
 rather than left implicit because a reader who meets the line deserves to know
-what set it. A `public-target` scope asks the forge whether the destination is
-public, and it asks by running `gh api repos/<owner>/<repo> --jq .visibility`;
-a `git-remote` target asks by running `git remote get-url origin`. PATH answers
+what set it. A `public-target` scope asks whether the destination is public, and
+where this repository has not declared its own `visibility` — or where the
+command named a destination, which a declaration does not speak for — it asks
+by running `gh api repos/<owner>/<repo> --jq .visibility`; a `git-remote` target
+asks by running `git remote get-url origin`, which is how an unnamed destination
+is resolved in the first place and so runs either way. PATH answers
 `gh` and `git` with the shim, so **every question this tool asks on the way to a
 verdict is a command it stands in front of**. On 2026-09-02 that closed into a
 loop against the released binary inside this repository's own checkout: the

src/guard/names.rs

@@ -42,6 +42,7 @@ use super::{Refusal, Request, Stage};
 use crate::config::{Policy, Rule};
 use crate::error::{Fatal, Result};
 use crate::git;
+use crate::shim::Silence;
 
 /// A repository name, with what a sentence put on the end taken off.
 ///
@@ -96,6 +97,15 @@ pub(crate) enum Visibility {
 pub(crate) struct Resolved {
     pub visibility: Visibility,
     pub canonical: Option<String>,
+    /// Why there was no answer, where there was none.
+    ///
+    /// `Visibility` says only that the check did not happen; this says which of
+    /// the four ways it did not, in the words the forge used. A caller that
+    /// refuses over an unchecked claim owes the reader that much -- "the forge
+    /// did not say" is the same sentence for a deleted repository and for an
+    /// account that is over its budget for the next eleven minutes, and only one
+    /// of those is worth waiting out.
+    pub silence: Option<Silence>,
 }
 
 /// Any `host.tld/owner/repo` or its scp-like `host.tld:owner/repo`, with the
@@ -383,28 +393,34 @@ pub(crate) fn lookup(cache: &mut BTreeMap<String, Resolved>, owner: &str, repo:
             Resolved {
                 visibility,
                 canonical,
+                silence: None,
             }
         }
-        // The forge said no. WHICH no it said is the whole question, and it is
-        // in stderr: `gh` writes `gh: Not Found (HTTP 404)` for a name it will
-        // not show us, and `gh: Bad credentials (HTTP 401)` for a client it
-        // will not talk to. Only the first is a fact about the name.
+        // The forge said no. WHICH no it said is the whole question, and
+        // [`Silence`] is where that line is drawn -- once, for this seam and for
+        // the two others that ask a forge the same kind of question. Only a
+        // `NotFound` is a fact about the name.
         //
         // Anything else -- 401, 403 and a rate limit, 5xx, a status line that
         // is not there, or no `gh` at all -- is the check not happening, and
         // reporting that as an inconclusive finding is how an unauthenticated
         // run passed every name in the tree.
-        Ok(output) => Resolved {
-            visibility: if String::from_utf8_lossy(&output.stderr).contains("(HTTP 404)") {
-                Visibility::Unknown
-            } else {
-                Visibility::Unavailable
-            },
-            canonical: None,
-        },
-        Err(_) => Resolved {
+        Ok(output) => {
+            let silence = Silence::of("gh", &output);
+            Resolved {
+                visibility: if silence == Silence::NotFound {
+                    Visibility::Unknown
+                } else {
+                    Visibility::Unavailable
+                },
+                canonical: None,
+                silence: Some(silence),
+            }
+        }
+        Err(error) => Resolved {
             visibility: Visibility::Unavailable,
             canonical: None,
+            silence: Some(Silence::unreachable("gh", &error)),
         },
     };
     cache.insert(key, resolved.clone());
@@ -626,6 +642,7 @@ fn judge(
                 Resolved {
                     visibility: Visibility::Private,
                     canonical: None,
+                    silence: None,
                 }
             } else {
                 lookup(&mut cache, &owner, &repo)
@@ -1306,6 +1323,7 @@ mod tests {
         Resolved {
             visibility,
             canonical: canonical.map(str::to_owned),
+            silence: None,
         }
     }
 

src/guard/push.rs

@@ -32,7 +32,7 @@ use super::{Refusal, Request};
 use crate::config::{Policy, Rule};
 use crate::error::Result;
 use crate::git;
-use crate::shim::Forge;
+use crate::shim::{Forge, Silence};
 
 /// Which seam is asking, for the two phrases that differ between them.
 ///
@@ -132,23 +132,13 @@ pub(crate) enum Owned {
     Yes,
     /// The forge answered, and neither is true.
     No,
-    /// No answer: no `gh` on PATH, no credentials, no network, or output that
-    /// is neither a yes nor a no. Carries the first line of what `gh` said, so
-    /// the reader is told which of those it was.
+    /// No answer: no `gh` on PATH, no credentials, a rate limit, no network, or
+    /// output that is neither a yes nor a no. Carries one whole sentence saying
+    /// which of those it was, because "the forge could not be asked" is a
+    /// different instruction to the reader in each case.
     CouldNotAsk(String),
 }
 
-/// The first line of what a failed `gh` wrote, which is the part worth printing.
-fn first_line(stderr: &[u8]) -> String {
-    let text = String::from_utf8_lossy(stderr);
-    let line = text.lines().next().unwrap_or_default().trim().to_owned();
-    if line.is_empty() {
-        String::from("it said nothing")
-    } else {
-        line
-    }
-}
-
 /// Ask the forge whether the operator owns this destination, once per run.
 ///
 /// Only ever reached for a destination the allow-list has already refused, so
@@ -181,11 +171,13 @@ fn ask_forge(owner: &str, key: &str) -> Owned {
         Ok(output) if output.status.success() => {
             String::from_utf8_lossy(&output.stdout).trim().to_owned()
         }
-        Ok(output) => return Owned::CouldNotAsk(first_line(&output.stderr)),
-        Err(error) => return Owned::CouldNotAsk(format!("gh could not be run ({error})")),
+        Ok(output) => return Owned::CouldNotAsk(Silence::of("gh", &output).sentence()),
+        Err(error) => {
+            return Owned::CouldNotAsk(Silence::unreachable("gh", &error).sentence());
+        }
     };
     if login.is_empty() {
-        return Owned::CouldNotAsk(String::from("`gh api user` printed no login"));
+        return Owned::CouldNotAsk(String::from("`gh api user` exited 0 and printed no login."));
     }
     // GitHub logins are case-insensitive, and a pin written in the case the
     // profile page shows is the same account as one written in the case a url
@@ -205,18 +197,22 @@ fn ask_forge(owner: &str, key: &str) -> Owned {
                 // `permissions` block that is not there answers `null`. Neither
                 // is a no about ownership.
                 other => Owned::CouldNotAsk(format!(
-                    "`gh api repos/{key}` answered {other:?}, which is neither true nor false"
+                    "`gh api repos/{key}` answered {other:?}, which is neither true nor false."
                 )),
             }
         }
-        // A 404 here is a definite no, and only because the request above
-        // succeeded: the client works and is authenticated, and a forge that
-        // will not show this repository to that identity is not a forge saying
-        // the identity administers it. Every other failure -- 401, 403, a rate
-        // limit, 5xx -- is the check not happening.
-        Ok(output) if String::from_utf8_lossy(&output.stderr).contains("(HTTP 404)") => Owned::No,
-        Ok(output) => Owned::CouldNotAsk(first_line(&output.stderr)),
-        Err(error) => Owned::CouldNotAsk(format!("gh could not be run ({error})")),
+        // Classified once, by the one classifier this binary has for the
+        // question -- see [`Silence`]. A 404 here is a definite no, and only
+        // because the request above succeeded: the client works and is
+        // authenticated, and a forge that will not show this repository to that
+        // identity is not a forge saying the identity administers it. Every
+        // other failure -- 401, 403, a rate limit, 5xx -- is the check not
+        // happening, and each of them says so in its own words.
+        Ok(output) => match Silence::of("gh", &output) {
+            Silence::NotFound => Owned::No,
+            silence => Owned::CouldNotAsk(silence.sentence()),
+        },
+        Err(error) => Owned::CouldNotAsk(Silence::unreachable("gh", &error).sentence()),
     }
 }
 
@@ -412,8 +408,8 @@ pub(crate) fn unowned(
         Some(Owned::CouldNotAsk(why)) => {
             return Err(crate::error::Fatal::new(format!(
                 "rule {:?}: {report}\n\nThe forge could not be asked whether you own {name}, \
-                 so the allow-list is the only answer there is and it is not a whole one: \
-                 {why}. Could not look is not a pass. Authenticate `gh`, or name the \
+                 so the allow-list is the only answer there is and it is not a whole one. \
+                 {why} Could not look is not a pass. Authenticate `gh`, or name the \
                  destination on the rule, or bypass this run deliberately with \
                  UPHOLD_ALLOW={}.",
                 rule.id, rule.id

src/guard/visibility.rs

@@ -32,6 +32,7 @@ use super::{Refusal, Request};
 use crate::config::visibility_is_public;
 use crate::error::{Fatal, Result};
 use crate::git;
+use crate::shim::Silence;
 
 /// Refuse a declared privacy the forge has stopped serving.
 ///
@@ -103,7 +104,8 @@ pub(crate) fn no_stale_visibility(request: &Request<'_>) -> Result<Option<Refusa
     // would not talk to us", which is exactly the line between a fact and an
     // absent check here.
     let mut cache = BTreeMap::new();
-    match lookup(&mut cache, &owner, &repo).visibility {
+    let resolved = lookup(&mut cache, &owner, &repo);
+    match resolved.visibility {
         Visibility::Public => Ok(Some(Refusal {
             id: id.clone(),
             report: format!(
@@ -119,20 +121,37 @@ pub(crate) fn no_stale_visibility(request: &Request<'_>) -> Result<Option<Refusa
             println!("{id}: declared {declared:?}, and the forge agrees.");
             Ok(None)
         }
-        // Neither of these disproves the declaration and neither confirms it.
+        // Neither of these disproves the declaration and neither confirms it,
+        // and both are exit 2 -- but they are not the same thing to be told, and
+        // for a while they were: `Unavailable` was reported in `Unknown`'s
+        // words, so an account eleven minutes into a rate limit read a paragraph
+        // about what a 404 means. The verdict is shared; the sentence is not.
+        //
         // `Unknown` is the forge answering that it will show us no repository by
         // this name, which for a repository declared private is the ordinary
         // answer to an unauthenticated request -- and it is also the answer for
-        // one that was deleted or renamed. `Unavailable` is no answer at all.
-        // Both are the check not happening, and a check that did not happen has
-        // never been a pass anywhere in this binary.
-        Visibility::Unknown | Visibility::Unavailable => Err(Fatal::new(format!(
+        // one that was deleted or renamed.
+        Visibility::Unknown => Err(Fatal::new(format!(
             "{id}: the forge did not say whether {owner}/{repo} is public, so the declared \
              {declared:?} was not checked. A 404 is a private repository, a deleted one, a \
              renamed one, and a request that carried no credentials -- this rule can \
              disprove a claim of privacy and can never confirm one, so it does not read \
              silence as agreement.\n\nCould not look is not a pass. Authenticate `gh`, or \
              bypass this run deliberately with UPHOLD_ALLOW={id}."
         ))),
+        // `Unavailable` is no answer at all, and which no-answer it was is the
+        // one thing the reader can act on -- a rate limit is waited out, an
+        // unauthenticated client is fixed, and neither is the 404 above.
+        Visibility::Unavailable => Err(Fatal::new(format!(
+            "{id}: the forge was not able to say whether {owner}/{repo} is public, so the \
+             declared {declared:?} was not checked. {}\n\nThis rule can disprove a claim of \
+             privacy and can never confirm one, so it does not read silence as agreement. \
+             Could not look is not a pass -- bypass this run deliberately with \
+             UPHOLD_ALLOW={id}.",
+            resolved.silence.as_ref().map_or_else(
+                || String::from("The forge gave no reason."),
+                Silence::sentence
+            )
+        ))),
     }
 }