housebroken-cli 0.6.8__tar.gz → 0.7.0__tar.gz

{housebroken_cli-0.6.8 → housebroken_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: housebroken-cli
-Version: 0.6.8
+Version: 0.7.0
 Summary: Agent-written pull requests that do not make a mess in someone else's house.
 Project-URL: Repository, https://github.com/lenamonj/housebroken
 License-Expression: MIT
@@ -52,10 +52,10 @@ the CLA known before filing, the SECURITY.md route taken when it applies
 A pull request passes through the door in order, and stops at the first rule it fails. Each rule is a script where a script can hold it. The maintainers' own verdicts that shaped them are kept separately, in [docs/lessons.md](https://github.com/lenamonj/housebroken/blob/main/docs/lessons.md).
 
 **1. Read the house rules before knocking.**
-`check-ai-policy.sh` reads every contributing guide, code of conduct, template and agent instruction file on the repository's branch and in the organization's `.github` repository, matched by name without regard to case, and prints each sentence that names AI with its reading: BAN, DISCLOSE, MENTION or CLEAN. A project that bans AI-written contributions never gets one. A project that asks for disclosure gets one truthful sentence in the body. `distinct-outside.sh` counts outside contributors merged in the last 120 days; a project that has merged none is closed to outsiders whatever its README says.
+`check-ai-policy.sh` reads every contributing guide, code of conduct, template and agent instruction file on the repository's branch and in the organization's `.github` repository, matched by name without regard to case (READMEs capped at 40, and the cap printed), and prints each sentence that names AI with its reading: BAN, DISCLOSE, MENTION or CLEAN. A file GitHub would not give, a throttled call or a truncated listing reads UNREAD, never CLEAN, and nothing files on it. A project that bans AI-written contributions never gets one. A project that asks for disclosure gets one truthful sentence in the body. `distinct-outside.sh` counts outside contributors merged in the last 120 days; a project that has merged none is closed to outsiders whatever its README says.
 
 **2. Is it already on the table?**
-`prior-art.sh` lists every issue and pull request, open, closed and merged, that touches the file or symbol, with the type taken from the API and the closing ruling quoted for every closed item. An open pull request that fixes the same thing, or a closed issue that ruled the behaviour intended, ends the work. A ruling is never argued with.
+`prior-art.sh` lists the issues and pull requests, open, closed and merged, that touch the file or symbol, with the type taken from the API and the closing ruling quoted for every closed item. A search that matched more than it returned says so, and such a printout is saved only when marked partial. The filing gate requires every file the branch changes to be one of its terms. An open pull request that fixes the same thing, or a closed issue that ruled the behaviour intended, ends the work. A ruling is never argued with.
 
 **3. Is it a fix or an opinion?**
 A change that rejects an input the project tolerated, changes a default, or narrows what the project publishes is the maintainer's call. It is sent with the call stated in the body: what breaks for existing users, and an offer to narrow or close it. A finding whose only evidence is a measurement is a hold, not a pull request.
@@ -67,7 +67,7 @@ On a fresh clone of the upstream default branch, the new test fails; with the pa
 The project's own test target on the fresh clone, and every gate its pull request workflow runs: lint, format, mutation, API check. A gate not run is a red check the maintainer sees first.
 
 **6. Match the house style.**
-`comment-check.sh` refuses any comment the branch adds to code, test files included; an existing comment may be reworded, a new file may open with the header its neighbours carry, and a maintainer's explicit request for documentation is the one exception. `comment-census.sh` measures density. The body is under 120 words, in the project's template, and says what was wrong, what changed and how it was verified, every sentence reproduced on the fresh clone. No tool footer, no session link, no co-author trailer, no typographic dash. `claim-check.sh` lists every counted or absolute claim in the body so each is re-derived against the exact revision it names.
+`comment-check.sh` refuses any comment the branch adds to code, test files included; an existing comment may be reworded, a new file may open with the header its neighbours carry, and a maintainer's explicit request for documentation is the one exception. `comment-census.sh` measures density. The body is under 120 words, in the project's template, and says what was wrong, what changed and how it was verified, every sentence reproduced on the fresh clone. No tool footer, no session link, no co-author trailer, no typographic dash. `claim-check.sh` lists every counted or absolute claim in the body so each is re-derived against the exact revision it names, and `ref-check.sh` looks up every issue number, link, test name, file and commit the body names, refusing one that does not exist.
 
 **7. Know the paperwork.**
 Before the first pull request to an organization: CLA, DCO, signed-commit requirement, disclosure trailer, and the identity clause. Author, committer and sign-off carry the contributor's real name.
@@ -76,16 +76,16 @@ Before the first pull request to an organization: CLA, DCO, signed-commit requir
 A memory-safety, remote-abort, injection or path-escape finding goes by the project's SECURITY.md route, privately, and never becomes a public pull request until the project answers.
 
 **9. File through the gate.**
-`branch-check.sh` refuses a dirty working tree, a file whose mode disagrees with its siblings, a file the repository's own `.gitignore` excludes, a working artifact, a commit carrying a tool trailer, a session link or a tool identity, a sign-off naming a username, a branch not on top of its base, and any comment added to code; it prints every absolute claim in added prose for falsification, and stamps the head it passed.
-`review.sh` names the adversarial reviewer: a different model from the one that wrote the change, one tier down, never below Sonnet. The reviewer gets a fresh context, hard read-only limits and an attack list that starts with every claim the prose makes and includes the form of the code: the reviewer writes the changed block the way the strongest engineer in that language would, in the repository's own idioms, and a smaller or clearer version is a finding; every finding carries evidence it produced itself, and its report is bound to the head and the text it read. A fix is a new head and gets a new review.
-`file-pr.sh` is the only way a pull request is opened. It refuses without a prior-art printout under a day old, a policy printout under a day old that does not read BAN, a body that discloses when the policy asks, a branch stamp for the exact head, and a POST AS IS review of that head and that body.
+`branch-check.sh` refuses a dirty working tree, a file whose mode disagrees with its siblings, a file the repository's own `.gitignore` excludes, a working artifact, a commit carrying a tool trailer, a session link or a tool identity, a sign-off naming a username, a branch not on top of its base, any comment added to code, a warning suppression that does not name what it hides or that no build log shows firing, reflection added to a .NET project that declares AOT or trim support without an AOT publish log of it, a credential or a path under your own home, a lockfile, generated file or binary nobody named, an agent's working file, and a file rewritten for its line endings; it notes a base the upstream has moved past, a user path that may be a fixture and every absolute claim in added prose, and stamps the head it passed.
+`review.sh` names the adversarial reviewer: a different model from the one that wrote the change, one tier down, never below Sonnet. The reviewer gets a fresh context, hard read-only limits, and before it reads the diff it writes its own fix from the bug alone, so it is not anchored on ours; the report names that fix as a diff and the gate refuses one that does not, a POST AS IS over an open BLOCKING or SHOULD FIX finding, and a POST AS IS over items the reviewer skipped. Its attack list starts with every claim the prose makes and includes the form of the code: the reviewer writes the changed block the way the strongest engineer in that language would, in the repository's own idioms, and a smaller or clearer version is a finding; every finding carries evidence it produced itself, and its report is bound to the head and the text it read. A fix is a new head and gets a new review.
+`file-pr.sh` is the only way a pull request is opened. It refuses without a prior-art printout under a day old that searched every file the branch changes, a policy printout under a day old that reads neither BAN nor UNREAD, a body that discloses when the policy asks and runs under 120 words of its own beside the project's template, a branch stamp for the exact head whose base the upstream has not since changed under the branch's files, a POST AS IS review of that head and that body, fewer than three open pull requests of yours on the repository, and ten minutes since the last.
 `file-issue.sh` is the only way an issue is opened. It refuses without the same prior-art and policy printouts, refuses the same prose, and refuses a body that mentions a fix, a patch or a pull request without a GitHub link to the branch or commit, so work that exists is attributable to whoever did it.
 
 **10. Watch it land.**
-`verify-filed-pr.sh` re-derives from GitHub that the head is the intended commit, the diff is exactly the intended files, and CI settled. `inbox.sh` prints every event on your threads since the last acknowledged cursor, bodies included, with a census of failing, blocked and conflicting checks. Every maintainer comment gets a same-day answer in the contributor's voice, checked by `claim-check.sh` and, when it concedes, disagrees or rides on a code change, by the adversarial review. Replies to one repository are spaced ten minutes apart. When the maintainer is right, concede in one sentence. A silent maintainer is never nudged.
+`verify-filed-pr.sh` re-derives from GitHub that the head is the intended commit, the files are the ones the branch stamp lists, the body is the one that was filed, and CI settled. `inbox.sh` prints every event on your threads since the last acknowledged cursor, bodies included, with a census of failing, blocked and conflicting checks. Every maintainer comment gets a same-day answer in the contributor's voice, checked by `claim-check.sh` and, when it concedes, disagrees or rides on a code change, by the adversarial review. Replies to one repository are spaced ten minutes apart. When the maintainer is right, concede in one sentence. A silent maintainer is never nudged.
 
 **11. Clean up.**
-`fork-hygiene.sh` deletes the fork branch of every merged or closed pull request and lists forks with no pull request left. No planning file, agent directory, journal or build output ever enters a diff.
+`fork-hygiene.sh` deletes the fork branch of every merged or closed pull request, unless an open one still uses it, and lists forks with no pull request left. No planning file, agent directory, journal or build output ever enters a diff.
 
 **12. Three per repository, one finding each.**
 A repository gets at most three open pull requests, each one finding, each meeting every rule above on its own, filed at least ten minutes apart.
@@ -121,7 +121,8 @@ uv tool install git+https://github.com/lenamonj/housebroken
 | `scripts/comment-census.sh` | added code versus added comments, per branch |
 | `scripts/diff-defaults.sh` | default arguments and one-line wrappers added to keep call sites untouched |
 | `scripts/claim-check.sh` | every falsifiable claim in a body or a reply, listed to re-derive |
-| `scripts/branch-check.sh` | the branch's mechanical facts: clean tree, modes, artifacts, trailers, sign-offs, comments, absolute claims |
+| `scripts/ref-check.sh` | every issue, link, test, file and commit a body names, looked up |
+| `scripts/branch-check.sh` | the branch's mechanical facts: clean tree, live base, modes, artifacts, secrets, generated files, trailers, sign-offs, comments, suppressions, absolute claims |
 | `scripts/review.sh` | the adversarial review: a different model attacks the change, and the filing is held to exactly what it read |
 | `scripts/file-pr.sh` | the only way a pull request gets filed: five gates in front of `gh pr create` |
 | `scripts/file-issue.sh` | the only way an issue gets filed: the same printouts and prose, and a fix offered is a fix linked |
@@ -137,6 +138,8 @@ The scripts are bash and need `gh` and `jq`. Each script's header says what it a
 
 housebroken does not find bugs and does not write patches. Any agent that produces a change can use it. It governs what leaves your machine and how it behaves once it arrives.
 
+The gates stop carelessness, not deceit. A stamp, a review report or a blind fix is a file the agent can write, and no script on the same machine can tell an honest one from a forged one. What the gates guarantee is that nothing files by accident: a step skipped, a check that failed, a base that moved, a reference to nothing.
+
 ## FAQ
 
 **Is this only for AI-written pull requests?**

{housebroken_cli-0.6.8 → housebroken_cli-0.7.0}/README.md

@@ -40,10 +40,10 @@ the CLA known before filing, the SECURITY.md route taken when it applies
 A pull request passes through the door in order, and stops at the first rule it fails. Each rule is a script where a script can hold it. The maintainers' own verdicts that shaped them are kept separately, in [docs/lessons.md](docs/lessons.md).
 
 **1. Read the house rules before knocking.**
-`check-ai-policy.sh` reads every contributing guide, code of conduct, template and agent instruction file on the repository's branch and in the organization's `.github` repository, matched by name without regard to case, and prints each sentence that names AI with its reading: BAN, DISCLOSE, MENTION or CLEAN. A project that bans AI-written contributions never gets one. A project that asks for disclosure gets one truthful sentence in the body. `distinct-outside.sh` counts outside contributors merged in the last 120 days; a project that has merged none is closed to outsiders whatever its README says.
+`check-ai-policy.sh` reads every contributing guide, code of conduct, template and agent instruction file on the repository's branch and in the organization's `.github` repository, matched by name without regard to case (READMEs capped at 40, and the cap printed), and prints each sentence that names AI with its reading: BAN, DISCLOSE, MENTION or CLEAN. A file GitHub would not give, a throttled call or a truncated listing reads UNREAD, never CLEAN, and nothing files on it. A project that bans AI-written contributions never gets one. A project that asks for disclosure gets one truthful sentence in the body. `distinct-outside.sh` counts outside contributors merged in the last 120 days; a project that has merged none is closed to outsiders whatever its README says.
 
 **2. Is it already on the table?**
-`prior-art.sh` lists every issue and pull request, open, closed and merged, that touches the file or symbol, with the type taken from the API and the closing ruling quoted for every closed item. An open pull request that fixes the same thing, or a closed issue that ruled the behaviour intended, ends the work. A ruling is never argued with.
+`prior-art.sh` lists the issues and pull requests, open, closed and merged, that touch the file or symbol, with the type taken from the API and the closing ruling quoted for every closed item. A search that matched more than it returned says so, and such a printout is saved only when marked partial. The filing gate requires every file the branch changes to be one of its terms. An open pull request that fixes the same thing, or a closed issue that ruled the behaviour intended, ends the work. A ruling is never argued with.
 
 **3. Is it a fix or an opinion?**
 A change that rejects an input the project tolerated, changes a default, or narrows what the project publishes is the maintainer's call. It is sent with the call stated in the body: what breaks for existing users, and an offer to narrow or close it. A finding whose only evidence is a measurement is a hold, not a pull request.
@@ -55,7 +55,7 @@ On a fresh clone of the upstream default branch, the new test fails; with the pa
 The project's own test target on the fresh clone, and every gate its pull request workflow runs: lint, format, mutation, API check. A gate not run is a red check the maintainer sees first.
 
 **6. Match the house style.**
-`comment-check.sh` refuses any comment the branch adds to code, test files included; an existing comment may be reworded, a new file may open with the header its neighbours carry, and a maintainer's explicit request for documentation is the one exception. `comment-census.sh` measures density. The body is under 120 words, in the project's template, and says what was wrong, what changed and how it was verified, every sentence reproduced on the fresh clone. No tool footer, no session link, no co-author trailer, no typographic dash. `claim-check.sh` lists every counted or absolute claim in the body so each is re-derived against the exact revision it names.
+`comment-check.sh` refuses any comment the branch adds to code, test files included; an existing comment may be reworded, a new file may open with the header its neighbours carry, and a maintainer's explicit request for documentation is the one exception. `comment-census.sh` measures density. The body is under 120 words, in the project's template, and says what was wrong, what changed and how it was verified, every sentence reproduced on the fresh clone. No tool footer, no session link, no co-author trailer, no typographic dash. `claim-check.sh` lists every counted or absolute claim in the body so each is re-derived against the exact revision it names, and `ref-check.sh` looks up every issue number, link, test name, file and commit the body names, refusing one that does not exist.
 
 **7. Know the paperwork.**
 Before the first pull request to an organization: CLA, DCO, signed-commit requirement, disclosure trailer, and the identity clause. Author, committer and sign-off carry the contributor's real name.
@@ -64,16 +64,16 @@ Before the first pull request to an organization: CLA, DCO, signed-commit requir
 A memory-safety, remote-abort, injection or path-escape finding goes by the project's SECURITY.md route, privately, and never becomes a public pull request until the project answers.
 
 **9. File through the gate.**
-`branch-check.sh` refuses a dirty working tree, a file whose mode disagrees with its siblings, a file the repository's own `.gitignore` excludes, a working artifact, a commit carrying a tool trailer, a session link or a tool identity, a sign-off naming a username, a branch not on top of its base, and any comment added to code; it prints every absolute claim in added prose for falsification, and stamps the head it passed.
-`review.sh` names the adversarial reviewer: a different model from the one that wrote the change, one tier down, never below Sonnet. The reviewer gets a fresh context, hard read-only limits and an attack list that starts with every claim the prose makes and includes the form of the code: the reviewer writes the changed block the way the strongest engineer in that language would, in the repository's own idioms, and a smaller or clearer version is a finding; every finding carries evidence it produced itself, and its report is bound to the head and the text it read. A fix is a new head and gets a new review.
-`file-pr.sh` is the only way a pull request is opened. It refuses without a prior-art printout under a day old, a policy printout under a day old that does not read BAN, a body that discloses when the policy asks, a branch stamp for the exact head, and a POST AS IS review of that head and that body.
+`branch-check.sh` refuses a dirty working tree, a file whose mode disagrees with its siblings, a file the repository's own `.gitignore` excludes, a working artifact, a commit carrying a tool trailer, a session link or a tool identity, a sign-off naming a username, a branch not on top of its base, any comment added to code, a warning suppression that does not name what it hides or that no build log shows firing, reflection added to a .NET project that declares AOT or trim support without an AOT publish log of it, a credential or a path under your own home, a lockfile, generated file or binary nobody named, an agent's working file, and a file rewritten for its line endings; it notes a base the upstream has moved past, a user path that may be a fixture and every absolute claim in added prose, and stamps the head it passed.
+`review.sh` names the adversarial reviewer: a different model from the one that wrote the change, one tier down, never below Sonnet. The reviewer gets a fresh context, hard read-only limits, and before it reads the diff it writes its own fix from the bug alone, so it is not anchored on ours; the report names that fix as a diff and the gate refuses one that does not, a POST AS IS over an open BLOCKING or SHOULD FIX finding, and a POST AS IS over items the reviewer skipped. Its attack list starts with every claim the prose makes and includes the form of the code: the reviewer writes the changed block the way the strongest engineer in that language would, in the repository's own idioms, and a smaller or clearer version is a finding; every finding carries evidence it produced itself, and its report is bound to the head and the text it read. A fix is a new head and gets a new review.
+`file-pr.sh` is the only way a pull request is opened. It refuses without a prior-art printout under a day old that searched every file the branch changes, a policy printout under a day old that reads neither BAN nor UNREAD, a body that discloses when the policy asks and runs under 120 words of its own beside the project's template, a branch stamp for the exact head whose base the upstream has not since changed under the branch's files, a POST AS IS review of that head and that body, fewer than three open pull requests of yours on the repository, and ten minutes since the last.
 `file-issue.sh` is the only way an issue is opened. It refuses without the same prior-art and policy printouts, refuses the same prose, and refuses a body that mentions a fix, a patch or a pull request without a GitHub link to the branch or commit, so work that exists is attributable to whoever did it.
 
 **10. Watch it land.**
-`verify-filed-pr.sh` re-derives from GitHub that the head is the intended commit, the diff is exactly the intended files, and CI settled. `inbox.sh` prints every event on your threads since the last acknowledged cursor, bodies included, with a census of failing, blocked and conflicting checks. Every maintainer comment gets a same-day answer in the contributor's voice, checked by `claim-check.sh` and, when it concedes, disagrees or rides on a code change, by the adversarial review. Replies to one repository are spaced ten minutes apart. When the maintainer is right, concede in one sentence. A silent maintainer is never nudged.
+`verify-filed-pr.sh` re-derives from GitHub that the head is the intended commit, the files are the ones the branch stamp lists, the body is the one that was filed, and CI settled. `inbox.sh` prints every event on your threads since the last acknowledged cursor, bodies included, with a census of failing, blocked and conflicting checks. Every maintainer comment gets a same-day answer in the contributor's voice, checked by `claim-check.sh` and, when it concedes, disagrees or rides on a code change, by the adversarial review. Replies to one repository are spaced ten minutes apart. When the maintainer is right, concede in one sentence. A silent maintainer is never nudged.
 
 **11. Clean up.**
-`fork-hygiene.sh` deletes the fork branch of every merged or closed pull request and lists forks with no pull request left. No planning file, agent directory, journal or build output ever enters a diff.
+`fork-hygiene.sh` deletes the fork branch of every merged or closed pull request, unless an open one still uses it, and lists forks with no pull request left. No planning file, agent directory, journal or build output ever enters a diff.
 
 **12. Three per repository, one finding each.**
 A repository gets at most three open pull requests, each one finding, each meeting every rule above on its own, filed at least ten minutes apart.
@@ -109,7 +109,8 @@ uv tool install git+https://github.com/lenamonj/housebroken
 | `scripts/comment-census.sh` | added code versus added comments, per branch |
 | `scripts/diff-defaults.sh` | default arguments and one-line wrappers added to keep call sites untouched |
 | `scripts/claim-check.sh` | every falsifiable claim in a body or a reply, listed to re-derive |
-| `scripts/branch-check.sh` | the branch's mechanical facts: clean tree, modes, artifacts, trailers, sign-offs, comments, absolute claims |
+| `scripts/ref-check.sh` | every issue, link, test, file and commit a body names, looked up |
+| `scripts/branch-check.sh` | the branch's mechanical facts: clean tree, live base, modes, artifacts, secrets, generated files, trailers, sign-offs, comments, suppressions, absolute claims |
 | `scripts/review.sh` | the adversarial review: a different model attacks the change, and the filing is held to exactly what it read |
 | `scripts/file-pr.sh` | the only way a pull request gets filed: five gates in front of `gh pr create` |
 | `scripts/file-issue.sh` | the only way an issue gets filed: the same printouts and prose, and a fix offered is a fix linked |
@@ -125,6 +126,8 @@ The scripts are bash and need `gh` and `jq`. Each script's header says what it a
 
 housebroken does not find bugs and does not write patches. Any agent that produces a change can use it. It governs what leaves your machine and how it behaves once it arrives.
 
+The gates stop carelessness, not deceit. A stamp, a review report or a blind fix is a file the agent can write, and no script on the same machine can tell an honest one from a forged one. What the gates guarantee is that nothing files by accident: a step skipped, a check that failed, a base that moved, a reference to nothing.
+
 ## FAQ
 
 **Is this only for AI-written pull requests?**

{housebroken_cli-0.6.8 → housebroken_cli-0.7.0}/bin/housebroken

@@ -50,6 +50,7 @@ usage: housebroken <subcommand> [args...]
   6  census      added code lines against added comment lines, per branch
   6  comments    refuse a comment added to code nobody asked for
   6  claims      every falsifiable claim in outbound text, listed to re-derive
+  6  refs        every issue, link, test, file and commit the text names, looked up
   9  branch      the mechanical facts about the branch: tree, modes, artifacts, claims
   9  review      a different model attacks the change before it is filed
   9  file        the only way a pull request gets filed
@@ -96,6 +97,7 @@ case "$cmd" in
   census)    script=comment-census.sh ;;
   comments)  script=comment-check.sh ;;
   claims)    script=claim-check.sh ;;
+  refs)      script=ref-check.sh ;;
   branch)    script=branch-check.sh ;;
   review)    script=review.sh ;;
   file)      script=file-pr.sh ;;

{housebroken_cli-0.6.8 → housebroken_cli-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "housebroken-cli"
-version = "0.6.8"
+version = "0.7.0"
 description = "Agent-written pull requests that do not make a mess in someone else's house."
 dynamic = ["readme"]
 license = "MIT"

housebroken_cli-0.7.0/scripts/branch-check.sh

@@ -0,0 +1,342 @@
+#!/bin/bash
+# branch-check.sh - the mechanical facts about the branch you are about to file.
+#
+# What you tested is what you file, and the branch carries nothing the project
+# did not ask for. Refused: a dirty working tree; a file whose mode disagrees
+# with its own siblings; a file the branch adds that the repository's own
+# .gitignore excludes; a working artifact; a commit carrying a tool trailer, a
+# session link or a tool identity; a sign-off naming a username; a branch that
+# is not on top of its base; and a comment added to code, test files included,
+# unless a maintainer asked for it (comment-check.sh); a warning suppression the
+# branch adds, until a build log shows the warning it suppresses firing; and
+# reflection added to a .NET project that declares itself AOT compatible or
+# trimmable, until an AOT publish log is given. shouldly #1335 suppressed an
+# IL2075 that never fired, and the reflection under it found nothing under
+# Native AOT. Absolute claims in added prose are printed for you to falsify one
+# by one; some of them are true.
+#
+# A branch that passes gets a stamp at $HOUSEBROKEN_HOME/branch-checks/<head>,
+# which file-pr.sh requires for the head it files.
+#
+# Usage:
+#   bash branch-check.sh [CLONE] [--base REF] [--asked URL]
+#                        [--warning-log FILE] [--aot-log FILE]
+#   bash branch-check.sh --help
+#
+# CLONE defaults to the current directory. REF defaults to the first of
+# upstream/main, upstream/master, origin/main, origin/master that resolves.
+# --asked URL is the maintainer's request for documentation, which turns the
+# comment refusal into a check. --warning-log FILE is a build log of the
+# branch without its suppressions; it must name every warning id they suppress.
+# --aot-log FILE is the output of an AOT publish (dotnet publish
+# -p:PublishAot=true) of the branch, run and read.
+#
+# Exits 0 when nothing blocks, 1 on a refusal, 2 on a usage error.
+set -u
+
+usage() { awk 'NR>1 && /^#/ {sub(/^# ?/, ""); print; next} NR>1 {exit}' "$0"; }
+
+here=$(cd "$(dirname "$0")" && pwd)
+home="${HOUSEBROKEN_HOME:-$HOME/.housebroken}"
+clone="."
+base=""
+asked=""
+warnlog=""
+aotlog=""
+allows=()
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --help|-h) usage; exit 0 ;;
+    --base)
+      shift
+      base="${1:-}"
+      [ -n "$base" ] || { echo "REFUSED: --base needs a ref" >&2; exit 2; }
+      ;;
+    --base=*) base="${1#--base=}" ;;
+    --asked)
+      shift
+      asked="${1:-}"
+      [ -n "$asked" ] || { echo "REFUSED: --asked needs the URL of the maintainer's ask" >&2; exit 2; }
+      ;;
+    --asked=*) asked="${1#--asked=}" ;;
+    --warning-log)
+      shift
+      warnlog="${1:-}"
+      [ -f "$warnlog" ] || { echo "REFUSED: --warning-log needs a build log file" >&2; exit 2; }
+      ;;
+    --aot-log)
+      shift
+      aotlog="${1:-}"
+      [ -f "$aotlog" ] || { echo "REFUSED: --aot-log needs an AOT publish log file" >&2; exit 2; }
+      ;;
+    --allow)
+      shift
+      [ -n "${1:-}" ] || { echo "REFUSED: --allow needs a path" >&2; exit 2; }
+      allows+=("$1")
+      ;;
+    -*) echo "REFUSED: unknown option $1" >&2; exit 2 ;;
+    *) clone="$1" ;;
+  esac
+  shift
+done
+
+cd "$clone" 2>/dev/null || { echo "REFUSED: $clone is not a directory" >&2; exit 2; }
+git rev-parse --git-dir >/dev/null 2>&1 || { echo "REFUSED: $clone is not a git clone" >&2; exit 2; }
+
+if [ -z "$base" ]; then
+  for candidate in upstream/main upstream/master origin/main origin/master; do
+    if git rev-parse --verify -q "$candidate" >/dev/null 2>&1; then base="$candidate"; break; fi
+  done
+fi
+[ -n "$base" ] || { echo "REFUSED: no base ref resolved - pass --base REF" >&2; exit 2; }
+git rev-parse --verify -q "$base" >/dev/null 2>&1 || { echo "REFUSED: base $base does not resolve" >&2; exit 2; }
+
+blocked=0
+block() { echo "REFUSED: $*"; blocked=1; }
+# Whether the base already carries a path. "rev:path" is not used because Git
+# for Windows' shell rewrites an argument shaped like "a/b:.c/d" as a path list.
+in_base() { [ -n "$(git ls-tree --name-only "$base" -- "$1" 2>/dev/null)" ]; }
+
+echo "== branch check: $(git rev-parse --abbrev-ref HEAD) against $base =="
+
+# What you tested is what you file, or you do not know what you are filing.
+dirty=$(git status --porcelain)
+if [ -n "$dirty" ]; then
+  block "the working tree is dirty, so the commits are not what you tested"
+  printf '%s\n' "$dirty" | sed 's/^/    /'
+fi
+
+# A base nobody fetched is the upstream as it was, not as it is: ask the remote.
+full=$(git rev-parse --symbolic-full-name "$base" 2>/dev/null)
+case "$full" in
+  refs/remotes/*/*)
+    rest="${full#refs/remotes/}"; remote="${rest%%/*}"; rbranch="${rest#*/}"
+    live=$(git ls-remote "$remote" "refs/heads/$rbranch" 2>/dev/null | awk '{print $1}')
+    if [ -z "$live" ]; then
+      block "cannot read $rbranch from $remote, so whether $base is current is unknown"
+    elif [ "$live" != "$(git rev-parse "$base")" ]; then
+      echo "CHECK: the base moved: $remote has $rbranch at ${live:0:12}, $base is $(git rev-parse --short=12 "$base") - file-pr.sh refuses when the new commits touch this branch's files"
+    fi
+    ;;
+  *) block "base $base is not a remote-tracking ref, so whether it is current cannot be checked - pass --base <remote>/<branch>" ;;
+esac
+
+if ! git merge-base --is-ancestor "$base" HEAD 2>/dev/null; then
+  block "HEAD is not on top of $base - rebase before filing"
+fi
+
+files=$(git diff --name-only "$base..HEAD" 2>/dev/null)
+if [ -z "$files" ]; then
+  block "no files differ from $base - there is nothing to file"
+fi
+
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  entry=$(git ls-files -s -- "$f" 2>/dev/null)
+  [ -n "$entry" ] || continue
+  mode=$(printf '%s\n' "$entry" | awk '{print $1}')
+
+  # A mode is only wrong relative to the file's own neighbours, and only the
+  # branch's to answer for when the base does not already carry it.
+  base_mode=$(git ls-tree "$base" -- "$f" 2>/dev/null | awk '{print $1}')
+  if [ "$mode" = "100755" ] && [ "$base_mode" != "100755" ]; then
+    case "$f" in
+      *.*) ext=".${f##*.}" ;;
+      *) ext="" ;;
+    esac
+    if [ -n "$ext" ]; then
+      sibs=$(git ls-files -s -- "*$ext" 2>/dev/null | awk -v self="$f" '$4 != self {print $1}')
+      norm=$(printf '%s\n' "$sibs" | grep -c '^100644$')
+      exec=$(printf '%s\n' "$sibs" | grep -c '^100755$')
+      if [ "$norm" -gt "$exec" ]; then
+        block "$f is committed 100755 but $norm of its $ext siblings are 100644"
+      fi
+    fi
+  fi
+
+  # The repository's own .gitignore is the authority on what is build output,
+  # but only for a file this branch adds. Ignore rules never apply to a file the
+  # project already tracks, which is why check-ignore skips tracked files unless
+  # forced. NVIDIA/go-nvml ignores "dl" for a built binary, and that pattern also
+  # matches the directory pkg/dl, so forcing the check called two upstream source
+  # files build output.
+  if ! in_base "$f"; then
+    if git check-ignore -q --no-index -- "$f" 2>/dev/null; then
+      block "$f is added by this branch and the repository's .gitignore excludes it"
+    fi
+  fi
+
+  case "$f" in
+    .jeffy/*|*/.jeffy/*|PLAN.md|*/PLAN.md|JOURNAL.md|*/JOURNAL.md|*.orig|*.rej|*.bak|*.swp|.DS_Store|*/.DS_Store|Thumbs.db|*/Thumbs.db)
+      block "$f is a working artifact and has no place in the diff" ;;
+  esac
+  # An agent's instruction or scratch file is an artifact when this branch adds
+  # it; a project that already keeps one may have it edited.
+  case "$f" in
+    .claude/*|*/.claude/*|.cursor/*|*/.cursor/*|CLAUDE.md|*/CLAUDE.md|AGENTS.md|*/AGENTS.md|GEMINI.md|*/GEMINI.md|STATUS.md|*/STATUS.md|NOTES.md|*/NOTES.md|TODO.md|*/TODO.md)
+      in_base "$f" || block "$f is added by this branch and reads as an agent's working file" ;;
+  esac
+done <<EOF
+$files
+EOF
+
+# A tool trailer is the one thing in a commit that cannot be argued as style.
+# Trailers are matched at the start of a line and a tool by its commit
+# identity, so a subject that only names a trailer is not refused.
+trailers=$(git log --format='%h author %an <%ae>, committer %cn <%ce>%n%b' "$base..HEAD" 2>/dev/null \
+  | grep -iE '^co-authored-by:.*(claude|anthropic|copilot|cursor|aider|codex|gemini)|^claude-session:|claude\.ai/code/session_|generated with .*claude|noreply@anthropic\.com|cursoragent@cursor\.com|noreply@aider\.chat')
+if [ -n "$trailers" ]; then
+  block "a commit carries a tool trailer or a session link, or a tool identity, which no project asked for"
+  printf '%s\n' "$trailers" | sed 's/^/    /'
+fi
+
+# DCO wants a human being. A one-word name is taken for a username whatever
+# its case; a real one-word name is refused as well, which is the price of
+# catching them.
+usernames=$(git log --format='%b' "$base..HEAD" 2>/dev/null | grep -E '^Signed-off-by: [^ <]+ <')
+if [ -n "$usernames" ]; then
+  block "a Signed-off-by names a username; the DCO asks for a real name"
+  printf '%s\n' "$usernames" | sed 's/^/    /'
+fi
+
+# A comment added to somebody else's code is refused unless its maintainer
+# asked for it; a reworded comment and a new file's opening header pass.
+comment_args=(--base "$base")
+[ -n "$asked" ] && comment_args+=(--asked "$asked")
+comments=$(bash "$here/comment-check.sh" . "${comment_args[@]}" 2>&1); comment_rc=$?
+case "$comment_rc" in
+  0) ;;
+  1) block "the branch adds comments to code that nobody asked for"
+     printf '%s\n' "$comments" | grep -E '^(REFUSED|CHECK): ' | sed 's/^REFUSED: /    /' ;;
+  *) block "comment-check.sh could not run: $comments" ;;
+esac
+printf '%s\n' "$comments" | grep -E '^CHECK: ' | sed 's/^/    /'
+
+# A suppression hides a warning from the maintainer too, so it has to be shown
+# that the warning exists. A suppression covering nothing usually covers code
+# that is wrong in a way the analyzer cannot see.
+added=$(git diff -U0 "$base..HEAD" -- . ':(exclude)*.md' ':(exclude)*.rst' ':(exclude)*.txt' 2>/dev/null \
+  | grep '^+' | grep -v '^+++' | sed 's/^+//')
+suppressions=$(printf '%s\n' "$added" | grep -E 'UnconditionalSuppressMessage|SuppressMessage\(|#pragma warning disable|pragma warning *\( *disable|<NoWarn>|@SuppressWarnings|@SuppressLint|@Suppress\(|#!?\[allow\(|nolint|NOLINT|NOSONAR|noqa|eslint-disable|@ts-ignore|@ts-expect-error|type: *ignore|pylint: *disable|rubocop:disable|swiftlint:disable|phpstan-ignore|psalm-suppress')
+if [ -n "$suppressions" ]; then
+  # Each suppression names what it hides: a code such as IL2075 or C4996, else
+  # the rule names after its keyword (errcheck, no-unused-vars). One that names
+  # nothing hides every warning on its line, and no log can show what it covers.
+  unshown=""
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    ids=$(printf '%s\n' "$line" | grep -oE '\b([A-Za-z]{1,6}[0-9]{3,5}|[0-9]{4})\b' | sort -u)
+    if [ -z "$ids" ]; then
+      ids=$(printf '%s\n' "$line" | sed -E 's/ -- .*//; s/.*(nolint|NOLINT|NOSONAR|noqa|eslint-disable(-next-line|-line)?|pylint: *disable|rubocop:disable|swiftlint:disable(:next|:this)?|phpstan-ignore(-next-line|-line)?|psalm-suppress|#!?\[allow|@Suppress(Warnings|Lint)?|SuppressMessage|ts-ignore|ts-expect-error|type: *ignore)//; s/ *(\/\/|#).*//' \
+        | grep -oE '[A-Za-z][A-Za-z0-9_-]{2,}' | grep -vxE 'disable|enable|next|line|this' | sort -u)
+    fi
+    if [ -z "$ids" ]; then
+      unshown="$unshown [names no warning: $(printf '%s' "$line" | sed 's/^[[:space:]]*//' | cut -c1-60)]"
+    elif [ -z "$warnlog" ]; then
+      unshown="$unshown $(printf '%s' "$ids" | tr '\n' ' ')(no --warning-log given)"
+    else
+      for id in $ids; do grep -qF -- "$id" "$warnlog" || unshown="$unshown $id"; done
+    fi
+  done <<< "$suppressions"
+  if [ -n "$unshown" ]; then
+    block "the branch adds a warning suppression, and no build log shows the warning firing ($unshown)"
+    printf '%s\n' "$suppressions" | sed 's/^/    /'
+  fi
+fi
+
+# The trim analyzer does not flag object.GetType().GetProperty(...), so a clean
+# build proves nothing about reflection under Native AOT; only a publish does.
+aotdecl=$(git grep -lE '<(IsAotCompatible|IsTrimmable|PublishAot|EnableTrimAnalyzer|EnableAotAnalyzer)( [^>]*)?>[[:space:]]*true' HEAD -- '*.csproj' '*.props' '*.targets' 2>/dev/null \
+  | sed 's/^HEAD://' | tr '\n' ' ')
+if [ -n "$aotdecl" ]; then
+  reflection=$(git diff -U0 "$base..HEAD" -- '*.cs' 2>/dev/null | grep '^+' | grep -v '^+++' | sed 's/^+//' \
+    | grep -E '\.Get(Property|Properties|Method|Methods|Field|Fields|Member|Members|Interfaces)\(|Activator\.CreateInstance|MakeGenericType|MakeGenericMethod|Type\.GetType\(|\.InvokeMember\(')
+  # The log has to be a publish of this repository: it names, as a word, a
+  # declaring project, or any project here when the declaration is in a .props.
+  published=0
+  if [ -n "$aotlog" ] && grep -q "Generating native code" "$aotlog"; then
+    for p in $aotdecl; do
+      case "$p" in
+        *.csproj) projs=$(basename "$p" .csproj) ;;
+        *) projs=$(git ls-files '*.csproj' | sed 's#.*/##; s/\.csproj$//') ;;
+      esac
+      for proj in $projs; do grep -qwF -- "$proj" "$aotlog" && published=1; done
+    done
+  fi
+  if [ -n "$reflection" ] && [ "$published" -eq 0 ]; then
+    block "the branch adds reflection to a project that declares AOT or trim support (${aotdecl% }), and no --aot-log shows an AOT publish of it"
+    printf '%s\n' "$reflection" | sed 's/^/    /'
+  fi
+fi
+
+# What embarrasses a contributor first, file by file: a secret or a personal
+# path in an added line, a lockfile or generated file, a binary, and a file
+# rewritten for its line endings or whitespace. --allow PATH names a file the
+# change really is about, such as a dependency bump's lockfile.
+allowed() { local a; for a in ${allows[@]+"${allows[@]}"}; do [ "$1" = "$a" ] && return 0; done; return 1; }
+# A credential anywhere is refused, and so is a path under this user's own
+# home; a path under another user's is a fixture or an example, and is noted.
+me=$(basename "${HOME:-/nobody}")
+leak_re="gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY|xox[baprs]-[A-Za-z0-9-]{10,}|sk-[A-Za-z0-9_-]{20,}|[A-Za-z]:[\\\\/]Users[\\\\/]$me([\\\\/ ]|\$)|/home/$me/|/Users/$me/|/mnt/[a-z]/Users/$me/"
+path_re='[A-Za-z]:[\\/]Users[\\/][^\\/ ]+|/home/[a-z][a-z0-9_-]*/|/Users/[A-Za-z][^/ ]*/|/mnt/[a-z]/Users/'
+nfiles=0; nadded=0
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  nfiles=$((nfiles + 1))
+  stat=$(git diff --numstat "$base..HEAD" -- "$f" | head -1)
+  case "$f" in *test*|*spec*) ;; *) nadded=$((nadded + $(printf '%s' "$stat" | awk '{print ($1 == "-") ? 0 : $1}'))) ;; esac
+  allowed "$f" && continue
+  addedf=$(git diff -U0 "$base..HEAD" -- "$f" | grep '^+' | grep -v '^+++')
+  leaks=$(printf '%s\n' "$addedf" | grep -oE "$leak_re" | sort -u)
+  [ -z "$leaks" ] || block "$f adds a personal path or a credential: $(printf '%s' "$leaks" | tr '\n' ' ')"
+  paths=$(printf '%s\n' "$addedf" | grep -oE "$path_re" | sort -u)
+  [ -z "$paths" ] || echo "CHECK: $f adds a user path, a fixture or an example unless it is yours: $(printf '%s' "$paths" | tr '\n' ' ')"
+  case "$f" in
+    package-lock.json|*/package-lock.json|yarn.lock|*/yarn.lock|pnpm-lock.yaml|*/pnpm-lock.yaml|Cargo.lock|*/Cargo.lock|go.sum|*/go.sum|poetry.lock|*/poetry.lock|uv.lock|*/uv.lock|Gemfile.lock|*/Gemfile.lock|composer.lock|*/composer.lock|packages.lock.json|*/packages.lock.json|vendor/*|*/vendor/*|node_modules/*|*/node_modules/*|*.min.js|*.pb.go|*_generated.*|*.g.cs|*.designer.cs|*.Designer.cs)
+      block "$f is a lockfile, vendored or generated file - a build rewrote it, or pass --allow $f if the change is about it" ;;
+  esac
+  case "$stat" in
+    -*) block "$f is binary - pass --allow $f if the change needs it" ;;
+    *)
+      total=$(printf '%s' "$stat" | awk '{print $1 + $2}')
+      real=$(git diff --numstat --ignore-space-at-eol --ignore-cr-at-eol "$base..HEAD" -- "$f" | awk '{print $1 + $2}')
+      if [ "$total" -ge 10 ] && [ $((${real:-0} * 2)) -lt "$total" ]; then
+        block "$f changes $total lines, of which ${real:-0} differ beyond whitespace and line endings - restore the file's own endings"
+      fi
+      ;;
+  esac
+done <<EOF
+$files
+EOF
+if [ "$nfiles" -gt 4 ] || [ "$nadded" -gt 150 ]; then
+  echo "CHECK: $nfiles files and $nadded added lines outside tests - one finding, the smallest diff that fixes it"
+fi
+
+# Absolutes in added prose are the claims a maintainer can falsify in one grep.
+claims=$(git diff -U0 "$base..HEAD" -- '*.md' '*.mdx' '*.rst' '*.txt' 2>/dev/null \
+  | grep '^+' | grep -v '^+++' | sed 's/^+//' \
+  | grep -nEi '\b(only|exactly|always|never|guaranteed|nothing|everything)\b')
+if [ -n "$claims" ]; then
+  echo "CHECK: added prose makes absolute claims - falsify each one against the code:"
+  printf '%s\n' "$claims" | sed 's/^/    /'
+fi
+
+echo
+echo "commits:"
+git log --oneline "$base..HEAD" | sed 's/^/    /'
+echo "diff (against the merge base, which is what the maintainer sees):"
+git diff --stat "$(git merge-base "$base" HEAD)..HEAD" | sed 's/^/    /'
+
+if [ "$blocked" -ne 0 ]; then
+  echo
+  echo "branch-check: refused. Fix the causes above; a refusal is a result."
+  exit 1
+fi
+# The stamp file-pr.sh reads: this head passed, against this base, at this
+# time, changing these files.
+head=$(git rev-parse HEAD)
+mkdir -p "$home/branch-checks"
+printf 'head: %s\nbase: %s\nbase-ref: %s\nchecked: %s\n' "$head" "$(git rev-parse "$base")" "$base" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$home/branch-checks/$head"
+printf '%s\n' "$files" | sed '/^$/d; s/^/file: /' >> "$home/branch-checks/$head"
+echo
+echo "branch-check: nothing mechanical blocks this branch."