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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: housebroken-cli
-Version: 0.6.9
+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, any comment added to code, a warning suppression no build log shows firing, and reflection added to a .NET project that declares AOT or trim support without an AOT publish log; 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 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 and the gate refuses one that does not. 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, 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.9 → 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, any comment added to code, a warning suppression no build log shows firing, and reflection added to a .NET project that declares AOT or trim support without an AOT publish log; 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 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 and the gate refuses one that does not. 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, 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.9 → 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.9 → housebroken_cli-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "housebroken-cli"
-version = "0.6.9"
+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.6.9 → housebroken_cli-0.7.0}/scripts/branch-check.sh

@@ -43,6 +43,7 @@ base=""
 asked=""
 warnlog=""
 aotlog=""
+allows=()
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --help|-h) usage; exit 0 ;;
@@ -68,6 +69,11 @@ while [ "$#" -gt 0 ]; do
       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
@@ -87,6 +93,9 @@ git rev-parse --verify -q "$base" >/dev/null 2>&1 || { echo "REFUSED: base $base
 
 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 =="
 
@@ -97,6 +106,21 @@ if [ -n "$dirty" ]; then
   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
@@ -136,16 +160,22 @@ while IFS= read -r f; do
   # 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 ! git cat-file -e "$base:$f" 2>/dev/null; then
+  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)
+    .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
@@ -187,15 +217,27 @@ printf '%s\n' "$comments" | grep -E '^CHECK: ' | sed 's/^/    /'
 # 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|@SuppressWarnings|@Suppress\(|#!?\[allow\(|nolint|NOLINT|noqa|eslint-disable|@ts-ignore|@ts-expect-error|type: *ignore|pylint: *disable|rubocop:disable|swiftlint:disable')
+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
-  ids=$(printf '%s\n' "$suppressions" | grep -oE '\b[A-Z]{1,4}[0-9]{3,5}\b' | sort -u)
+  # 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=""
-  if [ -z "$warnlog" ]; then
-    unshown="no --warning-log given"
-  else
-    for id in $ids; do grep -q "$id" "$warnlog" || unshown="$unshown $id"; done
-  fi
+  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/^/    /'
@@ -209,12 +251,67 @@ aotdecl=$(git grep -lE '<(IsAotCompatible|IsTrimmable|PublishAot|EnableTrimAnaly
 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\(')
-  if [ -n "$reflection" ] && ! { [ -n "$aotlog" ] && grep -q "Generating native code" "$aotlog"; }; then
-    block "the branch adds reflection to a project that declares AOT or trim support (${aotdecl% }), and no --aot-log shows an AOT publish"
+  # 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/^+//' \
@@ -235,9 +332,11 @@ if [ "$blocked" -ne 0 ]; then
   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.
+# 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."

{housebroken_cli-0.6.9 → housebroken_cli-0.7.0}/scripts/check-ai-policy.sh

@@ -12,21 +12,29 @@
 # repository.
 #
 # Usage:
-#   bash check-ai-policy.sh [--branch <name>] [--out] owner/repo [owner/repo ...]
+#   bash check-ai-policy.sh [--branch <name>] [--out] [--accept-truncated] owner/repo [owner/repo ...]
 #   bash check-ai-policy.sh --help
 #
 #   --branch <name>  read this branch instead of the default; some projects
 #                    keep the policy on a development branch
 #   --out            also save the printout to $HOUSEBROKEN_HOME/policy/
-#                    policy-<owner>-<repo>.md, which file-pr.sh reads
+#                    policy-<owner>-<repo>.md, which file-pr.sh reads, and
+#                    the pull request template to template-<owner>-<repo>.md,
+#                    whose lines file-pr.sh leaves out of the body's word count
+#   --accept-truncated  read a repository whose tree GitHub truncates (over
+#                    100,000 entries) after its policy was read by hand; the
+#                    printout records that it was
 #
 # Every hit is printed with its file and line so the sentence is read, not a
 # verdict. The RESULT line is the reading: BAN when a sentence forbids or
 # closes AI-written contributions, DISCLOSE when a sentence requires that AI
 # use be disclosed, MENTION when AI is named without either, CLEAN when no
-# policy file names it. Exit 0 for CLEAN or MENTION, 3 for DISCLOSE, 4 for BAN,
-# 1 when the repository cannot be read. With several repositories the exit is
-# the highest.
+# policy file names it, UNREAD when GitHub refused, throttled or truncated any
+# listing or file, so a failure is never read as silence. Every policy-named
+# file is read; READMEs are capped at 40 per repository and the cap is printed.
+# Exit 0 for CLEAN or MENTION, 1 for UNREAD or when the repository cannot be
+# read, 3 for DISCLOSE, 4 for BAN. With several repositories the exit is the
+# highest.
 #
 # Environment:
 #   HOUSEBROKEN_HOME  work directory, default $HOME/.housebroken; --out writes
@@ -41,7 +49,7 @@ usage() { awk 'NR>1 && /^#/ {sub(/^# ?/, ""); print; next} NR>1 {exit}' "$0"; }
 # regard to case, so CONTRIBUTING.rst, contributing.md and Contributing.md
 # are all read.
 NAME_RE='(^|/)(contributing([._-][a-z]+)?\.(md|rst|txt|adoc)|contributing|code[_-]?of[_-]?conduct\.(md|rst|txt)|readme\.(md|rst|txt|adoc)|ai([_-]policy)?\.md|policy\.md|agents?\.md|claude\.md|gemini\.md|copilot-instructions\.md|\.cursorrules|\.cursor/rules/[^/]+|pull_request_template(\.md)?|pull_request_template/[^/]+\.md|issue_template/[^/]+\.(md|yml|yaml)|governance\.md|maintainers\.md)$'
-MAX_FILES=40
+MAX_READMES=40
 
 # The word itself, plus its usual spellings and the tools by name.
 PATTERN='\bAI\b|\bA\.I\.|[Aa]rtificial [Ii]ntelligence|\bLLMs?\b|[Ll]arge [Ll]anguage [Mm]odels?|Copilot|ChatGPT|[Cc]laude|[Gg]enerative|[Mm]achine-generated|[Cc]odex\b|[Cc]ursor\b|[Aa]gentic'
@@ -50,6 +58,7 @@ DISCLOSE_RE='disclos|disclaimer|declare|must (state|say|note|indicate|mention)|b
 
 branch_opt=""
 out=0
+accept_truncated=0
 repos=()
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -58,6 +67,7 @@ while [ "$#" -gt 0 ]; do
               branch_opt="$1" ;;
     --branch=*) branch_opt="${1#--branch=}" ;;
     --out) out=1 ;;
+    --accept-truncated) accept_truncated=1 ;;
     --*) usage >&2; echo "check-ai-policy.sh: unknown option $1" >&2; exit 1 ;;
     */*) repos+=("$1") ;;
     *) usage >&2; echo "check-ai-policy.sh: '$1' is not owner/repo" >&2; exit 1 ;;
@@ -68,20 +78,50 @@ done
 
 command -v gh >/dev/null 2>&1 || { echo "check-ai-policy.sh: gh is not on PATH" >&2; exit 1; }
 home="${HOUSEBROKEN_HOME:-$HOME/.housebroken}"
+errfile=$(mktemp)
+tmpl_repo=$(mktemp)
+tmpl_org=$(mktemp)
+trap 'rm -f "$errfile" "$tmpl_repo" "$tmpl_org"' EXIT
 
-# List the policy files at one ref of one repository, from its tree listing.
-policy_files() {
-  gh api "repos/$1/git/trees/$2?recursive=1" --jq '.tree[] | select(.type == "blob") | .path' 2>/dev/null \
-    | grep -Ei "$NAME_RE" | head -"$MAX_FILES"
-}
-
-# Print every hit in one repository at one ref; sets found, ban, disclose.
+# Print every hit in one repository at one ref; sets found, ban, disclose,
+# and counts what GitHub would not give us in unread and truncated, so a
+# failed or throttled call is never read as a clean file.
 scan() {
-  local target="$1" ref="$2" label="$3" f body hits
+  local target="$1" ref="$2" label="$3" f body hits tree listed files readmes
+  if ! tree=$(gh api "repos/$target/git/trees/$ref?recursive=1" 2>"$errfile"); then
+    # An empty repository answers 409: it has no files, so no policy to read.
+    if grep -q "409" "$errfile"; then
+      echo "  (empty) $label$target"
+      return
+    fi
+    echo "  UNREAD: the file listing of $target@$ref"
+    unread=$((unread + 1))
+    return
+  fi
+  if [ "$(printf '%s' "$tree" | jq -r '.truncated')" = "true" ]; then
+    echo "  TRUNCATED: GitHub listed only part of the tree of $target@$ref"
+    truncated=1
+  fi
+  listed=$(printf '%s' "$tree" | jq -r '.tree[] | select(.type == "blob") | .path' | grep -Ei "$NAME_RE")
+  # Every policy-named file is read; only READMEs, which monorepos carry by the
+  # hundred, are capped, and the cap is printed.
+  readmes=$(printf '%s\n' "$listed" | grep -iE '(^|/)readme\.[a-z]+$')
+  files=$( { printf '%s\n' "$listed" | grep -viE '(^|/)readme\.[a-z]+$'
+             printf '%s\n' "$readmes" | head -"$MAX_READMES"; } | grep -v '^$')
+  if [ "$(printf '%s\n' "$readmes" | grep -c .)" -gt "$MAX_READMES" ]; then
+    echo "  (only the first $MAX_READMES of $(printf '%s\n' "$readmes" | grep -c .) READMEs in $label${target} were read)"
+  fi
   while IFS= read -r f; do
     [ -n "$f" ] || continue
-    body=$(gh api "repos/$target/contents/$f?ref=$ref" --jq '.content' 2>/dev/null | base64 -d 2>/dev/null)
-    [ -n "$body" ] || continue
+    if ! body=$(gh api "repos/$target/contents/$f?ref=$ref" --jq '.content' 2>/dev/null); then
+      echo "  UNREAD: $label$f"
+      unread=$((unread + 1))
+      continue
+    fi
+    body=$(printf '%s' "$body" | base64 -d 2>/dev/null)
+    if printf '%s' "$f" | grep -qiE '(^|/)pull_request_template'; then
+      printf '%s\n' "$body" >> "$tmplout"
+    fi
     hits=$(printf '%s' "$body" | grep -nE "$PATTERN" | head -20)
     if [ -n "$hits" ]; then
       found=1
@@ -92,12 +132,13 @@ scan() {
     else
       echo "  (clean) $label$f"
     fi
-  done < <(policy_files "$target" "$ref")
+  done <<< "$files"
 }
 
 status=0
 for repo in "${repos[@]}"; do
-  found=0; ban=0; disclose=0
+  found=0; ban=0; disclose=0; unread=0; truncated=0
+  : > "$tmpl_repo"; : > "$tmpl_org"
   report=$(
     echo "## AI policy: $repo"
     echo "read: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
@@ -110,14 +151,26 @@ for repo in "${repos[@]}"; do
       exit 1
     fi
     echo "branch: $branch"
+    tmplout="$tmpl_repo"
     scan "$repo" "$branch" ""
     org="${repo%%/*}"
-    org_branch=$(gh api "repos/$org/.github" --jq .default_branch 2>/dev/null) || org_branch=""
+    # A missing .github repository is a 404; any other failure is a policy we did not read.
+    if ! org_branch=$(gh api "repos/$org/.github" --jq .default_branch 2>"$errfile"); then
+      org_branch=""
+      grep -q "404" "$errfile" || { echo "  UNREAD: $org/.github"; unread=$((unread + 1)); }
+    fi
     if [ -n "$org_branch" ]; then
       echo "org repo: $org/.github ($org_branch)"
+      tmplout="$tmpl_org"
       scan "$org/.github" "$org_branch" "$org/.github: "
     fi
+    if [ "$truncated" -eq 1 ] && [ "$accept_truncated" -eq 1 ]; then
+      echo "truncated tree accepted by --accept-truncated: files GitHub did not list were not read"
+      truncated=0
+    fi
     if [ "$ban" -eq 1 ]; then echo "RESULT: BAN (a policy file forbids or closes AI-written contributions; never file here)"
+    elif [ "$unread" -gt 0 ]; then echo "RESULT: UNREAD ($unread policy file(s) or listing(s) could not be fetched; rerun when GitHub answers)"
+    elif [ "$truncated" -eq 1 ]; then echo "RESULT: UNREAD (GitHub truncated the file listing; read the policy by hand, then rerun with --accept-truncated)"
     elif [ "$disclose" -eq 1 ]; then echo "RESULT: DISCLOSE (a policy file requires AI use to be disclosed; say so in the body)"
     elif [ "$found" -eq 1 ]; then echo "RESULT: MENTION (a policy file names AI; read the lines above and decide)"
     else echo "RESULT: CLEAN (no policy file names AI)"
@@ -129,11 +182,19 @@ for repo in "${repos[@]}"; do
   case "$report" in
     *"RESULT: BAN"*) [ "$status" -lt 4 ] && status=4 ;;
     *"RESULT: DISCLOSE"*) [ "$status" -lt 3 ] && status=3 ;;
+    *"RESULT: UNREAD"*) [ "$status" -lt 1 ] && status=1 ;;
   esac
   if [ "$out" -eq 1 ]; then
     mkdir -p "$home/policy"
     printf '%s\n' "$report" > "$home/policy/policy-${repo%%/*}-${repo##*/}.md"
     echo "saved: $home/policy/policy-${repo%%/*}-${repo##*/}.md"
+    # The pull request template, the repository's own or else its
+    # organization's, is what file-pr.sh leaves out of the body's word count.
+    template="$home/policy/template-${repo%%/*}-${repo##*/}.md"
+    if [ -s "$tmpl_repo" ]; then cp "$tmpl_repo" "$template"
+    elif [ -s "$tmpl_org" ]; then cp "$tmpl_org" "$template"
+    else rm -f "$template"
+    fi
   fi
 done
 exit "$status"

{housebroken_cli-0.6.9 → housebroken_cli-0.7.0}/scripts/file-issue.sh

@@ -101,6 +101,7 @@ policy_result=$(grep -m1 '^RESULT: ' "$policy" | awk '{print $2}')
 case "$policy_result" in
   BAN) echo "REFUSED: $repo forbids AI-written contributions ($policy); never file here" >&2; exit 2 ;;
   DISCLOSE|MENTION|CLEAN) ;;
+  UNREAD) echo "REFUSED: $policy reads UNREAD - GitHub did not give every policy file; rerun check-ai-policy.sh --out" >&2; exit 2 ;;
   *) echo "REFUSED: $policy has no RESULT line - rerun check-ai-policy.sh --out" >&2; exit 2 ;;
 esac
 
@@ -150,9 +151,16 @@ if [ "$policy_result" = "DISCLOSE" ] && ! grep -qiE '\bAI\b|LLM|Claude|Copilot|C
   echo "REFUSED: $repo requires AI use to be disclosed ($policy) and the body does not name it" >&2
   exit 2
 fi
+if ! refs=$(bash "$(dirname "$0")/ref-check.sh" "$repo" "$bodyfile" 2>&1); then
+  echo "REFUSED: the body names something that does not exist:" >&2
+  printf '%s\n' "$refs" | grep -E 'NOT FOUND|REFUSED' >&2
+  exit 2
+fi
 
-offer_re='\b(fix|fixed|fixes|patch|patched|patches|pull request|PR)\b'
-link_re='https://github\.com/[^/[:space:]]+/[^/[:space:]]+/(tree|commit|compare|blob)/[^[:space:])]+'
+# An offer is a first-person promise of work, whatever noun it uses; "patch
+# release" in a bug report is not one. The link may be the filed pull request.
+offer_re='\b(I|we) (have|had|can|could|will|would|am|are)( be happy to| be glad to)? (send|open|submit|provide|offer|push|put up|prepare|write)\b|\b(I|we) (have|wrote|made) (a|the) (fix|patch|change)\b|\bsay the word\b|\bif you (want|would like|are interested)\b|\bhappy to (send|open|submit|provide)\b|\b(fix|fixes|patch|pull request|PR|change) (is |are )?(ready|available|done)\b'
+link_re='https://github\.com/[^/[:space:]]+/[^/[:space:]]+/(tree|commit|compare|blob|pull)/[^[:space:])]+'
 offer=$(printf '%s' "$body" | grep -ioE "$offer_re" | head -1) || true
 if [ -n "$offer" ] && ! printf '%s' "$body" | grep -qE "$link_re"; then
   echo "REFUSED: the body says '$offer' and links no branch or commit - push the work to your fork and link it, or take it out of the body" >&2

{housebroken_cli-0.6.9 → housebroken_cli-0.7.0}/scripts/file-pr.sh

@@ -106,6 +106,7 @@ policy_result=$(grep -m1 '^RESULT: ' "$policy" | awk '{print $2}')
 case "$policy_result" in
   BAN) echo "REFUSED: $repo forbids AI-written contributions ($policy); never file here" >&2; exit 2 ;;
   DISCLOSE|MENTION|CLEAN) ;;
+  UNREAD) echo "REFUSED: $policy reads UNREAD - GitHub did not give every policy file; rerun check-ai-policy.sh --out" >&2; exit 2 ;;
   *) echo "REFUSED: $policy has no RESULT line - rerun check-ai-policy.sh --out" >&2; exit 2 ;;
 esac
 
@@ -157,21 +158,53 @@ if [ "$bodyfile" = "-" ] || [ ! -f "$bodyfile" ]; then
 fi
 check_text "body file $bodyfile" "$(cat "$bodyfile")"
 check_text "--title" "$title"
-words=$(wc -w < "$bodyfile" | tr -d ' ')
+# The project's own template text is kept verbatim and is not ours to count:
+# HTML comments and every line the saved template carries, a ticked box read
+# as its unticked line, are left out before the words are counted.
+template="$home/policy/template-${repo%%/*}-${repo##*/}.md"
+[ -f "$template" ] || template=/dev/null
+words=$(awk -v T="$template" '
+  function norm(s) { gsub(/\[[xX]\]/, "[ ]", s); gsub(/^[[:space:]]+|[[:space:]]+$/, "", s); return s }
+  BEGIN { while ((getline l < T) > 0) { l = norm(l); if (l != "") t[l] = 1 } }
+  { l = norm($0); if (l in t) next
+    for (k in t) if (index(l, k) == 1) { l = substr(l, length(k) + 1); break }
+    print l }' "$bodyfile" | wc -w | tr -d ' ')
 if [ "$words" -gt 120 ]; then
-  echo "REFUSED: the body is $words words - say what was wrong, what the change does and how it was verified in 120 or fewer" >&2
+  echo "REFUSED: the body is $words words outside the project's template - say what was wrong, what the change does and how it was verified in 120 or fewer" >&2
   exit 2
 fi
 if [ "$policy_result" = "DISCLOSE" ] && ! grep -qiE '\bAI\b|LLM|Claude|Copilot|ChatGPT|language model|assist' "$bodyfile"; then
   echo "REFUSED: $repo requires AI use to be disclosed ($policy) and the body does not name it" >&2
   exit 2
 fi
+if ! refs=$(bash "$(dirname "$0")/ref-check.sh" "$repo" "$bodyfile" --clone . 2>&1); then
+  echo "REFUSED: the body names something that does not exist:" >&2
+  printf '%s\n' "$refs" | grep -E 'NOT FOUND|REFUSED' >&2
+  exit 2
+fi
 
 head=$(git rev-parse HEAD 2>/dev/null) || { echo "REFUSED: run file-pr.sh from inside the clone being filed" >&2; exit 2; }
 if [ ! -f "$home/branch-checks/$head" ]; then
   echo "REFUSED: branch-check.sh has not passed head ${head:0:12} - run it from this clone first" >&2
   exit 2
 fi
+# The prior art has to be about this change: every file the branch changes,
+# tests aside, is a term in the printout, by path or by name. One printout per
+# repository means another branch's run replaces it.
+searched=$(sed -n 's/^### //p' "$art" | tr -d '\r')
+ours=$(sed -n 's/^file: //p' "$home/branch-checks/$head" | tr -d '\r')
+[ -n "$ours" ] || { echo "REFUSED: the branch-check stamp for head ${head:0:12} lists no files - rerun branch-check.sh" >&2; exit 2; }
+unsearched=""
+while IFS= read -r f; do
+  case "$f" in ""|*test*|*Test*|*spec*) continue ;; esac
+  printf '%s\n' "$searched" | grep -qxF -e "$f" -e "$(basename "$f")" || unsearched="$unsearched $f"
+done <<EOF
+$ours
+EOF
+if [ -n "$unsearched" ]; then
+  echo "REFUSED: the prior art at $art never searched files this branch changes:$unsearched - rerun prior-art.sh $repo with them --out" >&2
+  exit 2
+fi
 # Every diff gate read the diff against the stamp's base; it must be the branch this files into.
 checked=$(sed -n 's/^base-ref: //p' "$home/branch-checks/$head" | tr -d '\r')
 if [ -z "$checked" ]; then
@@ -188,6 +221,48 @@ case "$checked" in
   *) echo "REFUSED: branch-check.sh measured this head against $checked, but it is filed into $target - rerun branch-check.sh --base <remote>/$target" >&2
      exit 2 ;;
 esac
+# The upstream may have moved since the check. A move that touches none of the
+# branch's files is reported; one that touches them means the branch and its
+# review were measured against code that is no longer there.
+stamped=$(sed -n 's/^base: //p' "$home/branch-checks/$head" | tr -d '\r')
+upstream=$(gh api "repos/$repo/branches/$target" --jq .commit.sha 2>/dev/null | tr -d '\r')
+[ -n "$upstream" ] || { echo "REFUSED: cannot read $target of $repo to confirm the base is current" >&2; exit 2; }
+if [ "$stamped" != "$upstream" ]; then
+  if ! cmp=$(gh api "repos/$repo/compare/$stamped...$upstream" 2>/dev/null); then
+    echo "REFUSED: the checked base ${stamped:0:12} is not on $repo $target - fetch, rebase and rerun branch-check.sh" >&2
+    exit 2
+  fi
+  # GitHub lists at most 300 files here; past that the overlap cannot be known.
+  if [ "$(printf '%s' "$cmp" | jq '.files | length')" -ge 300 ]; then
+    echo "REFUSED: $target moved by 300 files or more since branch-check (${stamped:0:12} to ${upstream:0:12}) - fetch, rebase, rerun branch-check.sh and the review" >&2
+    exit 2
+  fi
+  moved=$(printf '%s' "$cmp" | jq -r '.files[].filename')
+  overlap=$(printf '%s\n' "$moved" | grep -Fx -f <(printf '%s\n' "$ours"))
+  if [ -n "$overlap" ]; then
+    echo "REFUSED: $target moved since branch-check (${stamped:0:12} to ${upstream:0:12}) and changed files this branch changes - fetch, rebase, rerun branch-check.sh and the review:" >&2
+    printf '%s\n' "$overlap" | sed 's/^/    /' >&2
+    exit 2
+  fi
+  echo "note: $target moved since branch-check (${stamped:0:12} to ${upstream:0:12}); none of its new commits touch this branch's files" >&2
+fi
+# Three open pull requests per repository, and ten minutes between filings:
+# GitHub lets maintainers cap a non-collaborator's open pull requests, and two
+# stamped the same minute read as a bot.
+if ! mine=$(gh pr list -R "$repo" --author @me --state open --json createdAt --jq '[.[].createdAt] | sort' 2>/dev/null); then
+  echo "REFUSED: cannot read your open pull requests on $repo" >&2
+  exit 2
+fi
+open_count=$(printf '%s' "$mine" | jq 'length')
+if [ "$open_count" -ge 3 ]; then
+  echo "REFUSED: you have $open_count open pull requests on $repo - three is the most a repository gets" >&2
+  exit 2
+fi
+since=$(printf '%s' "$mine" | jq -r --argjson now "$(date -u +%s)" 'if length > 0 then $now - (last | fromdateiso8601) else 99999 end')
+if [ "$since" -lt 600 ]; then
+  echo "REFUSED: your last pull request on $repo was filed ${since}s ago - wait until ten minutes have passed" >&2
+  exit 2
+fi
 review="$home/reviews/review-${repo%%/*}-${repo##*/}-${head:0:12}.md"
 if [ ! -f "$review" ]; then
   echo "REFUSED: no adversarial review at $review - run review.sh brief and have a different model attack this head" >&2
@@ -201,4 +276,7 @@ if [ "${FILE_PR_DRY:-0}" = "1" ]; then
   printf '\n'
   exit 0
 fi
+# What was filed, kept so verify-filed-pr.sh can compare GitHub's copy to it.
+mkdir -p "$home/filed"
+cp "$bodyfile" "$home/filed/${repo%%/*}-${repo##*/}-$head.md"
 gh pr create -R "$repo" "${pass[@]}"

{housebroken_cli-0.6.9 → housebroken_cli-0.7.0}/scripts/fork-hygiene.sh

@@ -53,6 +53,17 @@ while read -r repo n; do
   IFS='|' read -r owner fork branch state <<< "$info"
   if [ "$owner" != "$ME" ] || [ -z "$branch" ]; then continue; fi
   gh api "repos/$ME/$fork/git/refs/heads/$branch" >/dev/null 2>&1 || continue
+  # A closed pull request refiled from the same branch still needs it, and
+  # deleting the branch would close the open one.
+  if ! users=$(gh pr list --repo "$repo" --head "$branch" --state open --json number,headRepositoryOwner \
+    --jq "[.[] | select(.headRepositoryOwner.login == \"$ME\") | .number] | join(\" \")" 2>/dev/null); then
+    echo "fork-hygiene.sh: cannot list open pull requests on $repo; $branch kept" >&2
+    continue
+  fi
+  if [ -n "$users" ]; then
+    echo "kept $ME/$fork $branch: open pull request $repo#$users still uses it"
+    continue
+  fi
   if [ "$DRY" = 1 ]; then
     echo "would delete $ME/$fork $branch ($state $repo#$n)"
     continue

{housebroken_cli-0.6.9 → housebroken_cli-0.7.0}/scripts/prior-art.sh

@@ -31,14 +31,16 @@ set -u
 
 usage() {
   cat <<'EOF'
-usage: prior-art.sh owner/repo <term>... [--out]
+usage: prior-art.sh owner/repo <term>... [--out [--partial]]
        prior-art.sh --help
 
   owner/repo  the upstream repository to search
   <term>      a symbol, phrase or file path; a term with a slash or a dot is
               also treated as a path: its commit history is scanned and
               every open PR that changes it is listed
-  --out       save the printout under $HOUSEBROKEN_HOME/prior-art/
+  --out       save the printout under $HOUSEBROKEN_HOME/prior-art/; a printout
+              whose searches matched more than they returned is not saved
+  --partial   save a partial printout anyway, marked as such
 
 environment:
   HOUSEBROKEN_HOME  work directory, default $HOME/.housebroken
@@ -54,10 +56,12 @@ command -v jq >/dev/null 2>&1 || { echo "prior-art.sh: jq is not on PATH" >&2; e
 
 repo=""
 out=0
+accept_partial=0
 terms=()
 for arg in "$@"; do
   case "$arg" in
     --out) out=1 ;;
+    --partial) accept_partial=1 ;;
     --*) usage >&2; echo "prior-art.sh: unknown option $arg" >&2; exit 1 ;;
     */*) if [ -z "$repo" ]; then repo="$arg"; else terms+=("$arg"); fi ;;
     *) if [ -z "$repo" ]; then usage >&2; exit 1; fi
@@ -70,6 +74,8 @@ fi
 
 home="${HOUSEBROKEN_HOME:-$HOME/.housebroken}"
 calls=0
+partial=0
+notes=""
 items=0
 tmp=$(mktemp) || { echo "prior-art.sh: cannot create temp file" >&2; exit 1; }
 row=$(mktemp) || { echo "prior-art.sh: cannot create temp file" >&2; exit 1; }
@@ -84,10 +90,20 @@ last_word() {
   printf '%s' "$body" | tr '\n\r\t|' '    ' | tr -s ' ' | cut -c1-160
 }
 
-emit() {
-  local kind num state date author title word=""
+emit() { # label for the counts: issues or pull requests
+  local label="$1" kind num state date author title word=""
   while IFS=$'\t' read -r kind num state date author title; do
     [ -n "$num" ] || continue
+    # The search's own count against the rows it returned: a term matching more
+    # than one page is a printout that has not read everything.
+    if [ "$kind" = "TOTAL" ]; then
+      if [ "$num" -gt "$state" ]; then
+        notes="${notes}showing $state of $num $label for '$term'; narrow the term
+"
+        partial=1
+      fi
+      continue
+    fi
     word=""
     if [ "$state" = "closed" ]; then word=$(last_word "$num" "$author"); calls=$((calls+1)); fi
     printf '| %s | #%s | %s | %s | %s | %s | %s |\n' \
@@ -106,20 +122,22 @@ for term in "${terms[@]}"; do
   } >>"$tmp"
 
   gh api -X GET search/issues -f q="repo:$repo type:issue \"$term\"" -F per_page=10 \
-    --jq '.items[] | ["issue", (.number|tostring), .state, ((.closed_at // .created_at)[0:10]),
-          .user.login, (.title|gsub("[|]";"/")|gsub("[\n\r\t]";" "))] | @tsv' >"$row" ||
+    --jq '(["TOTAL", (.total_count|tostring), (if .incomplete_results then "0" else (.items|length|tostring) end)] | @tsv),
+          (.items[] | ["issue", (.number|tostring), .state, ((.closed_at // .created_at)[0:10]),
+          .user.login, (.title|gsub("[|]";"/")|gsub("[\n\r\t]";" "))] | @tsv)' >"$row" ||
     { echo "prior-art.sh: issue search failed for $repo term '$term'" >&2; exit 1; }
   calls=$((calls+1))
-  emit
+  emit issues
 
   gh api -X GET search/issues -f q="repo:$repo type:pr \"$term\"" -F per_page=10 \
-    --jq '.items[] | ["PR", (.number|tostring),
+    --jq '(["TOTAL", (.total_count|tostring), (if .incomplete_results then "0" else (.items|length|tostring) end)] | @tsv),
+          (.items[] | ["PR", (.number|tostring),
           (if .pull_request.merged_at then "merged" else .state end),
           ((.pull_request.merged_at // .closed_at // .created_at)[0:10]),
-          .user.login, (.title|gsub("[|]";"/")|gsub("[\n\r\t]";" "))] | @tsv' >"$row" ||
+          .user.login, (.title|gsub("[|]";"/")|gsub("[\n\r\t]";" "))] | @tsv)' >"$row" ||
     { echo "prior-art.sh: PR search failed for $repo term '$term'" >&2; exit 1; }
   calls=$((calls+1))
-  emit
+  emit "pull requests"
 
   # a path term also gets the PRs whose merge commits touched that path
   case "$term" in
@@ -146,6 +164,13 @@ for term in "${terms[@]}"; do
                  ($p.title|gsub("[|]";"/")|gsub("[\n\r\t]";" ")), .] | @tsv' >"$openfiles" ||
           { echo "prior-art.sh: open PR listing failed for $repo" >&2; exit 1; }
         calls=$((calls+1))
+        open_total=$(gh api -X GET search/issues -f q="repo:$repo is:pr is:open" --jq .total_count 2>/dev/null) || open_total=""
+        calls=$((calls+1))
+        if [ -z "$open_total" ] || [ "$open_total" -gt 200 ]; then
+          notes="${notes}OPEN PR LIST INCOMPLETE: 200 of ${open_total:-an unknown number of} open pull requests read; one changing these paths may be missing
+"
+          partial=1
+        fi
         # GitHub returns at most 100 files per PR here; a larger PR is read in full
         awk -F'\t' '$5 == "MORE"' "$openfiles" | while IFS=$'\t' read -r num date author title _; do
           gh api --paginate "repos/$repo/pulls/$num/files?per_page=100" --jq '.[].filename' |
@@ -167,8 +192,16 @@ done
 printf '\n%d items across %d terms. Read every closed item before filing; this script lists, it does not judge.\n' \
   "$items" "${#terms[@]}" >>"$tmp"
 printf 'gh calls: %d\n' "$calls" >>"$tmp"
+if [ "$partial" -eq 1 ]; then
+  printf '\nPARTIAL: these searches returned less than they matched:\n%s' "$notes" >>"$tmp"
+  [ "$accept_partial" -eq 1 ] && printf 'saved with --partial: the rest was not read\n' >>"$tmp"
+fi
 
 cat "$tmp"
+if [ "$out" -eq 1 ] && [ "$partial" -eq 1 ] && [ "$accept_partial" -eq 0 ]; then
+  echo "prior-art.sh: not saved - the printout is partial; narrow the terms, or pass --partial to save it as read" >&2
+  exit 1
+fi
 if [ "$out" -eq 1 ]; then
   dir="$home/prior-art"
   mkdir -p "$dir" || { echo "prior-art.sh: cannot create $dir" >&2; exit 1; }

housebroken_cli-0.7.0/scripts/ref-check.sh

@@ -0,0 +1,114 @@
+#!/bin/bash
+# ref-check.sh - every reference in outbound text points at something that
+# exists.
+#
+# A model writes "Fixes #412", a link, a test name or a commit hash with the
+# same fluency whether the thing exists or not, and a maintainer who follows
+# one to nothing stops reading. Each reference is looked up: an issue or pull
+# request number on GitHub (its type and state printed, so "Fixes" naming a
+# merged pull request is visible), a github.com link, and, with --clone, a
+# file path, a test name or a commit hash named in backticks. Fenced code and
+# quoted lines are evidence, not references, and are skipped.
+#
+# Usage:
+#   bash ref-check.sh owner/repo FILE [--clone DIR]
+#   bash ref-check.sh --help
+#
+# Exits 0 when every reference was found, 1 when any was not, 2 on a usage
+# error. A lookup GitHub refuses reads NOT FOUND: unconfirmed is not found.
+#
+# Assumes gh is installed and authenticated. Read-only: GET calls only.
+set -u
+
+usage() { awk 'NR>1 && /^#/ {sub(/^# ?/, ""); print; next} NR>1 {exit}' "$0"; }
+
+case "${1:-}" in
+  --help|-h) usage; exit 0 ;;
+esac
+repo="${1:-}"; file="${2:-}"
+case "$repo" in */*) ;; *) echo "REFUSED: name the repository as owner/repo" >&2; exit 2 ;; esac
+[ -f "$file" ] || { echo "REFUSED: $file does not exist" >&2; exit 2; }
+shift 2
+clone=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --clone) clone="${2:-}"; [ -d "$clone" ] || { echo "REFUSED: --clone needs a directory" >&2; exit 2; }; shift ;;
+    *) echo "REFUSED: unknown argument $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+text=$(awk '/^(```|~~~)/ {fence = !fence; next} !fence && !/^ *>/ && !/^    / {print}' "$file")
+found() { echo "  found      $1"; }
+lost() { echo "  NOT FOUND  $1"; }
+
+# owner/repo#N and bare #N, the bare ones in this repository
+issue() { # owner/repo number label
+  local got
+  if got=$(gh api "repos/$1/issues/$2" --jq '(if .pull_request then "pull request" else "issue" end) + " " + .state + ": " + .title' 2>/dev/null); then
+    found "$3 ($got)"
+  else
+    lost "$3"
+  fi
+}
+out=$(
+  printf '%s\n' "$text" | grep -oE '\b[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+#[0-9]+\b' | sort -u | while IFS= read -r ref; do
+    issue "${ref%#*}" "${ref##*#}" "$ref"
+  done
+  printf '%s\n' "$text" | sed -E 's/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+#[0-9]+//g' | grep -oE '(^|[^A-Za-z0-9&/])#[0-9]+\b' \
+    | grep -oE '[0-9]+' | sort -un | while IFS= read -r n; do
+    issue "$repo" "$n" "#$n"
+  done
+  printf '%s\n' "$text" | grep -oE 'https://github\.com/[^ )>"]+' | sed 's/[.,;:]$//' | sort -u | while IFS= read -r url; do
+    path="${url#https://github.com/}"
+    case "$path" in
+      */*/pull/[0-9]*|*/*/issues/[0-9]*)
+        r=$(printf '%s' "$path" | cut -d/ -f1-2); n=$(printf '%s' "$path" | cut -d/ -f4 | grep -oE '^[0-9]+')
+        issue "$r" "$n" "$url" ;;
+      */*/commit/*)
+        r=$(printf '%s' "$path" | cut -d/ -f1-2); c=$(printf '%s' "$path" | cut -d/ -f4)
+        if gh api "repos/$r/commits/$c" --jq .sha >/dev/null 2>&1; then found "$url"; else lost "$url"; fi ;;
+      */*/blob/*|*/*/tree/*)
+        r=$(printf '%s' "$path" | cut -d/ -f1-2); ref=$(printf '%s' "$path" | cut -d/ -f4); p=$(printf '%s' "$path" | cut -d/ -f5- | sed 's/#.*//')
+        if gh api "repos/$r/contents/$p?ref=$ref" --jq 'if type == "array" then "dir" else .path end' >/dev/null 2>&1; then found "$url"; else lost "$url"; fi ;;
+    esac
+  done
+)
+
+# Names in backticks, checked against the clone: a path, a test, a commit.
+if [ -n "$clone" ]; then
+  # shellcheck disable=SC2016  # the backticks are the markdown being matched
+  names=$(printf '%s\n' "$text" | grep -oE '`[^`]+`' | tr -d '`' | sort -u)
+  local_out=$(printf '%s\n' "$names" | while IFS= read -r n; do
+    [ -n "$n" ] || continue
+    if printf '%s' "$n" | grep -qE '^[0-9a-f]{7,40}$'; then
+      if git -C "$clone" cat-file -e "$n^{commit}" 2>/dev/null; then found "commit $n"; else lost "commit $n"; fi
+    elif printf '%s' "$n" | grep -qE '^[A-Za-z0-9_./-]+\.[A-Za-z0-9]{1,6}$'; then
+      # A dotted name is a file when the clone has it; without a slash it may
+      # be an identifier (os.path, t.Run, v1.2.3), so only a path is NOT FOUND.
+      if git -C "$clone" ls-files --error-unmatch -- "$n" >/dev/null 2>&1 \
+        || git -C "$clone" ls-files | grep -qE "(^|/)$(printf '%s' "$n" | sed 's/[.[\*^$]/\\&/g')$"; then
+        found "file $n"
+      elif printf '%s' "$n" | grep -q /; then
+        lost "file $n"
+      fi
+    elif printf '%s' "$n" | grep -qE '^(Test[A-Z][A-Za-z0-9_]*|test_[A-Za-z0-9_]+|[A-Za-z0-9_]+_test|[A-Z][A-Za-z0-9_]*Tests?)$'; then
+      if git -C "$clone" grep -qw -- "$n" 2>/dev/null; then found "test $n"; else lost "test $n"; fi
+    fi
+  done)
+  out=$(printf '%s\n%s\n' "$out" "$local_out")
+fi
+out=$(printf '%s\n' "$out" | sed '/^$/d')
+
+if [ -z "$out" ]; then
+  echo "ref-check: no references in $file"
+  exit 0
+fi
+echo "ref-check: every reference in $file, looked up:"
+printf '%s\n' "$out"
+if printf '%s\n' "$out" | grep -q 'NOT FOUND'; then
+  echo
+  echo "ref-check: a reference points at nothing; fix it or drop it."
+  exit 1
+fi
+exit 0

{housebroken_cli-0.6.9 → housebroken_cli-0.7.0}/scripts/review.sh

@@ -216,9 +216,10 @@ EOF
   done
   printf 'author-model: %s\nreviewer-model: %s\n' "$author" "$reviewer"
   [ -n "$head" ] && printf 'blind-fix: %s\n' "$blind"
+  printf 'skipped: none | <the item numbers you did not attack, each with why>\n'
   printf 'verdict: POST AS IS | POST WITH CHANGES | DO NOT POST\n\n'
   cat <<'EOF'
-POST AS IS means nothing BLOCKING or SHOULD FIX remains. POST WITH CHANGES means the author fixes what you found and the fixed version comes back for another review. DO NOT POST means it should not go at all. After the header, number your findings, each with a severity (BLOCKING, SHOULD FIX or NIT), the evidence, and the exact fix, with replacement text in full for any wording. A report with no findings says what was checked and how.
+POST AS IS means nothing BLOCKING or SHOULD FIX remains and nothing was skipped. POST WITH CHANGES means the author fixes what you found and the fixed version comes back for another review. DO NOT POST means it should not go at all. An item that does not apply to this change is not skipped: say in its place why it does not apply. A skipped item is one you did not do, for time, tools or access, and the gate refuses POST AS IS over it. After the header, number your findings, each on its own line as "N. SEVERITY: title" with SEVERITY one of BLOCKING, SHOULD FIX or NIT, then the evidence, and the exact fix, with replacement text in full for any wording. The gate reads those lines: a BLOCKING or SHOULD FIX line under POST AS IS is refused, so a later round that lists an earlier round's findings as fixed renumbers them as NIT or drops the severity. A report with no findings says what was checked and how. The blind fix is a unified diff with its hunks.
 EOF
 }
 
@@ -261,8 +262,22 @@ cmd_check() {
     blind=$(field blind-fix)
     [ -n "$blind" ] || refuse "$report reviews code at ${head:0:12} and names no blind-fix: the reviewer's own fix, written before reading ours"
     [ -f "$blind" ] || refuse "the blind fix $blind named in $report does not exist"
+    if ! grep -qE '^(diff --git |--- )' "$blind" || ! grep -q '^@@' "$blind"; then
+      refuse "the blind fix $blind is not a diff: it must carry the reviewer's own change, hunks and all"
+    fi
   fi
 
+  # The verdict is the header; the findings are the body. A POST AS IS over an
+  # open BLOCKING or SHOULD FIX finding, or over items the reviewer never
+  # attacked, is a header that disagrees with its own report.
+  local skipped open
+  skipped=$(field skipped)
+  [ -n "$skipped" ] || refuse "$report has no skipped: line in its header - 'none', or the items not attacked"
+  printf '%s' "$skipped" | grep -qiE '^none\.?$' ||
+    refuse "the skipped: line must read exactly none for POST AS IS, or list the items not attacked ($skipped): attack them or review again"
+  open=$(grep -iE '^[[:space:]#*]*([0-9]+[.)]|[-*])[[:space:]*[]*(BLOCKING|SHOULD FIX)\b|^[[:space:]*-]*severity:[[:space:]*]*(BLOCKING|SHOULD FIX)\b' "$report")
+  [ -z "$open" ] || refuse "the verdict is POST AS IS but the report lists open findings: $(printf '%s' "$open" | head -1 | cut -c1-120)"
+
   if [ -n "$clone" ]; then
     now=$(git -C "$clone" rev-parse HEAD 2>/dev/null) || bad_usage "$clone is not a git clone"
     [ -n "$head" ] || refuse "$report records no head, so it cannot clear a branch"

{housebroken_cli-0.6.9 → housebroken_cli-0.7.0}/scripts/verify-filed-pr.sh

@@ -66,6 +66,36 @@ echo ""
 echo "-- files in the PR (what a reviewer sees)"
 view files '.files[] | "   " + .path + "  +" + (.additions|tostring) + "/-" + (.deletions|tostring)'
 
+# The intended files are the branch-check stamp's, and the intended body is the
+# copy file-pr.sh kept; GitHub's versions are compared to both.
+home="${HOUSEBROKEN_HOME:-$HOME/.housebroken}"
+stamp="$home/branch-checks/$head"
+intended=""
+[ -f "$stamp" ] && intended=$(sed -n 's/^file: //p' "$stamp" | tr -d '\r' | sort)
+if [ -n "$intended" ]; then
+  filed=$(view files '.files[].path' | sort)
+  if [ "$intended" = "$filed" ]; then
+    note "files match the stamp" "yes"
+  else
+    note "FILES DIFFER FROM STAMP" "$(diff <(printf '%s\n' "$intended") <(printf '%s\n' "$filed") | grep '^[<>]' | tr '\n' ' ')"
+    fail=1
+  fi
+else
+  note "files" "no branch-check stamp listing files for ${head:0:12}; not compared"
+fi
+kept="$home/filed/${repo%%/*}-${repo##*/}-$head.md"
+if [ -f "$kept" ]; then
+  norm() { tr -d '\r' | sed -e 's/[[:space:]]*$//' | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}'; }
+  if [ "$(view body .body | norm)" = "$(norm < "$kept")" ]; then
+    note "body matches what was filed" "yes"
+  else
+    note "BODY DIFFERS" "from $kept; read the diff, a maintainer may have edited it"
+    diff <(norm < "$kept") <(view body .body | norm) | head -20 | sed 's/^/    /'
+  fi
+else
+  note "body" "no filed copy for ${head:0:12}; not compared"
+fi
+
 echo ""
 echo "-- checks (waits until every check has settled)"
 gh pr checks "$pr" --repo "$repo" --watch --interval 20 >/dev/null 2>&1 || true

{housebroken_cli-0.6.9 → housebroken_cli-0.7.0}/skills/housebroken/SKILL.md

@@ -43,7 +43,10 @@ report it in one line and do not proceed to the next step.
    patch is worth. DISCLOSE means the body says, in one truthful sentence
    and in the template's own words where it has them, that AI was used and
    which tool. MENTION means read the lines and decide which of the two it
-   is. The printout is required by step 9. If the project accepts pull
+   is. UNREAD means GitHub did not give every policy file: wait and run it
+   again, never file on it; a repository too large for GitHub to list in
+   full reads UNREAD until you have read its policy by hand and passed
+   `--accept-truncated`. The printout is required by step 9. If the project accepts pull
    requests only for labelled issues, the deliverable is an issue with the
    fix offered, not a pull request. `housebroken outside owner/repo` counts
    outside contributors merged in the last 120 days. Zero means the project
@@ -56,8 +59,11 @@ report it in one line and do not proceed to the next step.
    every closed item. Read every closed item. An open pull request that fixes
    the same thing means you stop and say so. A closed issue that ruled the
    behavior intended means you stop and say so; you never argue with a
-   ruling. The printout is required by step 9; write it before the branch
-   exists.
+   ruling. A term that matches more than one page is printed as "showing N
+   of M" and the printout is not saved: narrow the term, or pass `--partial`
+   when you have read enough to say so. The printout is required by step 9;
+   write it before the branch exists, with every file the patch changes
+   among its terms, because the filing gate checks them against the branch.
 
 3. **Is it a fix or an opinion?**
    A change that rejects an input the project tolerated, changes a default,
@@ -136,7 +142,10 @@ report it in one line and do not proceed to the next step.
    the body and re-measure every line it lists, now, against the exact
    revision that sentence names. A claim that names its revision can still
    be wrong about it, which is why the listing is the whole gate: the
-   re-derivation is yours to do.
+   re-derivation is yours to do. Run `housebroken refs owner/repo <file>
+   --clone <clone>` too: every issue number, link, test name, file and
+   commit the text names is looked up, and one that does not exist stops
+   the filing.
 
 7. **Know the paperwork.**
    Before the first pull request to an organization, find its agreement: CLA,
@@ -157,11 +166,19 @@ report it in one line and do not proceed to the next step.
    whose mode disagrees with its own siblings, a file the branch adds that the
    repository ignores, a commit carrying a tool trailer, a session link or a
    tool identity, a sign-off that names a username, a branch that is not on
-   top of its base, any comment added to code (`--asked <URL>` when the
-   maintainer asked for it), a warning suppression the branch adds until
-   `--warning-log` shows each suppressed warning firing, and reflection added
-   to a .NET project that declares AOT or trim support until `--aot-log`
-   shows an AOT publish you ran the changed path under; it prints every absolute claim your added prose
+   top of its base, a base that is not a remote-tracking ref (it notes one the
+   upstream has moved past; the filing refuses it when the move touches your
+   files), any comment added to code
+   (`--asked <URL>` when the maintainer asked for it), a warning suppression
+   that names no warning or whose warning `--warning-log` does not show
+   firing, reflection added to a .NET project that declares AOT or trim
+   support until `--aot-log` shows an AOT publish of that project you ran the
+   changed path under, a credential or a path under your own home in an
+   added line, a
+   lockfile, vendored, generated or binary file (`--allow <path>` when the
+   change is about it), an agent's working file such as an added CLAUDE.md
+   or `.claude/`, and a file rewritten for its line endings or whitespace;
+   it prints every absolute claim your added prose
    makes so you can falsify each one against the code, and it stamps the
    head it passed, which the filing requires. Then the adversarial review:
    `housebroken review brief --author <your model> --repo owner/repo --clone <clone> --text <body file>`
@@ -180,26 +197,34 @@ report it in one line and do not proceed to the next step.
    the changed block the way the strongest engineer in that language would,
    and a smaller or clearer version is a finding you fix before filing. It
    writes its report where the brief says, with its own evidence behind
-   every finding. Every fix it asks for is a new head,
+   every finding, each on its own line as "N. SEVERITY: title", and a
+   `skipped:` header line that reads `none` or lists what it did not attack.
+   The gate refuses a blind fix that is not a diff, a POST AS IS over a
+   BLOCKING or SHOULD FIX line, and a POST AS IS over skipped items.
+   Every fix it asks for is a new head,
    and a new head is reviewed again. When it passes, re-read every claim it
    did not re-derive itself: a passed review is not a proof. Then
    `housebroken file owner/repo --title ... --body-file ...`, the only way a
    pull request is opened. Never run the pull request creation command
    directly. The gate refuses when the prior-art printout for that repository
-   is missing or older than a day, when the policy printout is missing, older
-   than a day or reads BAN, when the policy reads DISCLOSE and the body does
-   not disclose, when the body carries a footer, a trailer or a dash
-   character or runs past 120 words, when `housebroken branch` has not
-   stamped the exact head against the branch it is filed into (`--base`
-   to both when the project takes pull requests on a branch other than its
-   default), or when there is no POST AS IS review of the exact head and
-   body being filed.
+   is missing, older than a day or never searched a file the branch changes,
+   when the policy printout is missing, older than a day or reads BAN or
+   UNREAD, when the policy reads DISCLOSE and the body does not disclose,
+   when the body carries a footer, a trailer or a dash character, runs past
+   120 words of its own beside the project's template, or names an issue,
+   link, test, file or commit that does not exist, when `housebroken branch`
+   has not stamped the exact head against the branch it is filed into
+   (`--base` to both when the project takes pull requests on a branch other
+   than its default), when the upstream has since changed a file the branch
+   changes, when there is no POST AS IS review of the exact head and body
+   being filed, when you already have three open pull requests on the
+   repository, and when your last one there is under ten minutes old.
    A refusal is a result; fix the cause.
 
 10. **Watch it land.**
     `housebroken verify owner/repo PR` re-derives from GitHub that the head is
-    the intended commit, the diff is exactly the intended files, and CI
-    settled. `housebroken sweep` lists every open pull request where the ball
+    the intended commit, the files are the ones the branch stamp lists, the
+    body is the one that was filed, and CI settled. `housebroken sweep` lists every open pull request where the ball
     is in your court, and prints a `TIDY` line for every merged or closed
     pull request whose fork branch still exists, on every run until
     `housebroken hygiene` has deleted it. `housebroken inbox` is the first thing a session does
@@ -237,7 +262,8 @@ report it in one line and do not proceed to the next step.
 
 11. **Clean up.**
     `housebroken hygiene` deletes the fork branch of every merged or closed
-    pull request and lists forks with no pull request left; delete those when
+    pull request, unless an open one still uses it, and lists forks with no
+    pull request left; delete those when
     the work is over. No planning file, agent directory, journal or build
     output ever enters a diff.
 

housebroken_cli-0.7.0/src/housebroken/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.7.0"

housebroken_cli-0.6.9/src/housebroken/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.6.9"