housebroken-cli 0.5.0__tar.gz → 0.6.0__tar.gz

housebroken_cli-0.6.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: housebroken-cli
+Version: 0.6.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
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lenamonj/housebroken/main/assets/door.jpg" width="560" alt="A white ceramic robot dog sits at an open, lit door, a scroll in its mouth, its paws stopped at a glowing amber line on the threshold">
+</p>
+
+<h1 align="center">housebroken</h1>
+
+<p align="center"><em>Agent-written pull requests that do not make a mess in someone else's house.</em></p>
+
+<p align="center">
+  <img src="https://img.shields.io/github/stars/lenamonj/housebroken?style=flat-square&color=111111&label=stars" alt="Stars">
+  <img src="https://img.shields.io/github/v/release/lenamonj/housebroken?style=flat-square&color=111111&label=release" alt="Release">
+  <img src="https://img.shields.io/pypi/v/housebroken-cli?style=flat-square&color=111111&label=pypi" alt="PyPI">
+  <img src="https://img.shields.io/badge/works%20with-Claude%20Code-111111?style=flat-square" alt="Works with Claude Code">
+  <img src="https://img.shields.io/badge/shellcheck-clean-111111?style=flat-square" alt="shellcheck clean">
+  <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT license">
+</p>
+
+A maintainer runs her project on evenings and weekends. She opens GitHub to pull requests from accounts she has never seen, each rewriting a function she wrote years ago, each carrying comments in code that had none, a six-hundred-word body and a footer naming the tool that wrote it. She closes them without reading them, and she is right to.
+
+housebroken is the set of rules that get a pull request past her, written as scripts that refuse to file until every rule is met. The rules are principles, not opinions, and the scripts are the enforcement: a gate that only suggests is followed when remembered.
+
+## What passes the door
+
+```
+one finding, one pull request
+the smallest diff in the project's own style, no comment added to their code
+one test that fails on their main and passes with the patch
+a body under 120 words, in their template, no footer, no trailer
+their policy read first: no filing where AI is banned, disclosure where it is asked
+prior art read and quoted before the branch existed
+their CI target green on a fresh clone of their main
+attacked by a second model before it left, evidence behind every finding
+the CLA known before filing, the SECURITY.md route taken when it applies
+```
+
+## The rules
+
+<img align="right" width="230" src="https://raw.githubusercontent.com/lenamonj/housebroken/main/assets/treatise.jpg" alt="An obsidian book with chrome corners titled The Housebroken Agent, a treatise on manners for machines calling at the homes of maintainers">
+
+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.
+
+**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.
+
+**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.
+
+**4. Prove it red first, and prove the proof.**
+On a fresh clone of the upstream default branch, the new test fails; with the patch, it passes. Every arm of the experiment prints evidence that its precondition held, files are swapped by content and checked by hash, and two arms that agree exactly have not tested the variable.
+
+**5. Run their CI, not yours.**
+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.
+
+**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.
+
+**8. Security goes through the side door.**
+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; 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.
+
+**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.
+
+**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.
+
+**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.
+
+**13. Write it down before you leave.**
+A house rule learned about a repository goes into `notes.sh` the same session. A maintainer's verdict goes into docs/lessons.md the same day, quoted verbatim with the rule it became. A gate that was wrong, missing or done by hand becomes an issue before the run ends.
+
+## Install
+
+You need `bash`, `gh` (signed in) and `jq`. Then, from PyPI; `pipx install housebroken-cli` and `uv tool install housebroken-cli` work the same way:
+
+```
+pip install housebroken-cli
+housebroken install-skill
+```
+
+The first line puts the `housebroken` command on your path. The second puts the skill where Claude Code loads it, so the agent runs the door itself before it opens anything upstream. To run the main branch between releases, install from the repository instead:
+
+```
+uv tool install git+https://github.com/lenamonj/housebroken
+```
+
+`housebroken help` prints the door in order. Every gate is also a plain bash script under `scripts/`, runnable on its own.
+
+## What is in the repository
+
+| script | gate |
+|---|---|
+| `scripts/check-ai-policy.sh` | the AI-contribution policy, read where it lives, with its reading: BAN, DISCLOSE, MENTION, CLEAN |
+| `scripts/distinct-outside.sh` | outside contributors merged in 120 days |
+| `scripts/prior-art.sh` | issues and pull requests on the touched files, type stated, rulings quoted |
+| `scripts/comment-check.sh` | refuses a comment added to code nobody asked for |
+| `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/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/verify-filed-pr.sh` | the filed pull request is what was meant, and CI settled |
+| `scripts/pr-sweep.sh` | every open pull request where the ball is in your court |
+| `scripts/inbox.sh` | what GitHub has to tell you since you last looked, bodies included, with a census of every open pull request |
+| `scripts/notes.sh` | what this repository's maintainers have asked for before |
+| `scripts/fork-hygiene.sh` | branches deleted after merge or close, orphan forks listed |
+
+The scripts are bash and need `gh` and `jq`. Each script's header says what it assumes.
+
+## Not in scope
+
+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.
+
+## FAQ
+
+**Is this only for AI-written pull requests?**
+No. Every rule here predates agents. Agents made it cheap to break all of them at once, on a hundred repositories, before breakfast.
+
+**Does it make maintainers like agent pull requests?**
+No. It makes the pull request indistinguishable from a careful human's, and answers truthfully when they ask.
+
+**What if the maintainer closes it anyway?**
+Then the maintainer is the judge and the ruling stands. Read why, write it down, and if it is a class of mistake, make it a gate.
+
+**Why "housebroken"?**
+Because the alternative is what maintainers are calling it.
+
+## License
+
+MIT.

housebroken_cli-0.6.0/README.md

@@ -0,0 +1,142 @@
+<p align="center">
+  <img src="assets/door.jpg" width="560" alt="A white ceramic robot dog sits at an open, lit door, a scroll in its mouth, its paws stopped at a glowing amber line on the threshold">
+</p>
+
+<h1 align="center">housebroken</h1>
+
+<p align="center"><em>Agent-written pull requests that do not make a mess in someone else's house.</em></p>
+
+<p align="center">
+  <img src="https://img.shields.io/github/stars/lenamonj/housebroken?style=flat-square&color=111111&label=stars" alt="Stars">
+  <img src="https://img.shields.io/github/v/release/lenamonj/housebroken?style=flat-square&color=111111&label=release" alt="Release">
+  <img src="https://img.shields.io/pypi/v/housebroken-cli?style=flat-square&color=111111&label=pypi" alt="PyPI">
+  <img src="https://img.shields.io/badge/works%20with-Claude%20Code-111111?style=flat-square" alt="Works with Claude Code">
+  <img src="https://img.shields.io/badge/shellcheck-clean-111111?style=flat-square" alt="shellcheck clean">
+  <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT license">
+</p>
+
+A maintainer runs her project on evenings and weekends. She opens GitHub to pull requests from accounts she has never seen, each rewriting a function she wrote years ago, each carrying comments in code that had none, a six-hundred-word body and a footer naming the tool that wrote it. She closes them without reading them, and she is right to.
+
+housebroken is the set of rules that get a pull request past her, written as scripts that refuse to file until every rule is met. The rules are principles, not opinions, and the scripts are the enforcement: a gate that only suggests is followed when remembered.
+
+## What passes the door
+
+```
+one finding, one pull request
+the smallest diff in the project's own style, no comment added to their code
+one test that fails on their main and passes with the patch
+a body under 120 words, in their template, no footer, no trailer
+their policy read first: no filing where AI is banned, disclosure where it is asked
+prior art read and quoted before the branch existed
+their CI target green on a fresh clone of their main
+attacked by a second model before it left, evidence behind every finding
+the CLA known before filing, the SECURITY.md route taken when it applies
+```
+
+## The rules
+
+<img align="right" width="230" src="assets/treatise.jpg" alt="An obsidian book with chrome corners titled The Housebroken Agent, a treatise on manners for machines calling at the homes of maintainers">
+
+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.
+
+**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.
+
+**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.
+
+**4. Prove it red first, and prove the proof.**
+On a fresh clone of the upstream default branch, the new test fails; with the patch, it passes. Every arm of the experiment prints evidence that its precondition held, files are swapped by content and checked by hash, and two arms that agree exactly have not tested the variable.
+
+**5. Run their CI, not yours.**
+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.
+
+**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.
+
+**8. Security goes through the side door.**
+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; 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.
+
+**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.
+
+**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.
+
+**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.
+
+**13. Write it down before you leave.**
+A house rule learned about a repository goes into `notes.sh` the same session. A maintainer's verdict goes into docs/lessons.md the same day, quoted verbatim with the rule it became. A gate that was wrong, missing or done by hand becomes an issue before the run ends.
+
+## Install
+
+You need `bash`, `gh` (signed in) and `jq`. Then, from PyPI; `pipx install housebroken-cli` and `uv tool install housebroken-cli` work the same way:
+
+```
+pip install housebroken-cli
+housebroken install-skill
+```
+
+The first line puts the `housebroken` command on your path. The second puts the skill where Claude Code loads it, so the agent runs the door itself before it opens anything upstream. To run the main branch between releases, install from the repository instead:
+
+```
+uv tool install git+https://github.com/lenamonj/housebroken
+```
+
+`housebroken help` prints the door in order. Every gate is also a plain bash script under `scripts/`, runnable on its own.
+
+## What is in the repository
+
+| script | gate |
+|---|---|
+| `scripts/check-ai-policy.sh` | the AI-contribution policy, read where it lives, with its reading: BAN, DISCLOSE, MENTION, CLEAN |
+| `scripts/distinct-outside.sh` | outside contributors merged in 120 days |
+| `scripts/prior-art.sh` | issues and pull requests on the touched files, type stated, rulings quoted |
+| `scripts/comment-check.sh` | refuses a comment added to code nobody asked for |
+| `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/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/verify-filed-pr.sh` | the filed pull request is what was meant, and CI settled |
+| `scripts/pr-sweep.sh` | every open pull request where the ball is in your court |
+| `scripts/inbox.sh` | what GitHub has to tell you since you last looked, bodies included, with a census of every open pull request |
+| `scripts/notes.sh` | what this repository's maintainers have asked for before |
+| `scripts/fork-hygiene.sh` | branches deleted after merge or close, orphan forks listed |
+
+The scripts are bash and need `gh` and `jq`. Each script's header says what it assumes.
+
+## Not in scope
+
+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.
+
+## FAQ
+
+**Is this only for AI-written pull requests?**
+No. Every rule here predates agents. Agents made it cheap to break all of them at once, on a hundred repositories, before breakfast.
+
+**Does it make maintainers like agent pull requests?**
+No. It makes the pull request indistinguishable from a careful human's, and answers truthfully when they ask.
+
+**What if the maintainer closes it anyway?**
+Then the maintainer is the judge and the ruling stands. Read why, write it down, and if it is a class of mistake, make it a gate.
+
+**Why "housebroken"?**
+Because the alternative is what maintainers are calling it.
+
+## License
+
+MIT.

{housebroken_cli-0.5.0 → housebroken_cli-0.6.0}/bin/housebroken

@@ -48,6 +48,7 @@ usage: housebroken <subcommand> [args...]
   1  outside     count outside contributors merged in the last 120 days
   2  prior-art   issues and pull requests on the touched files, rulings quoted
   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
   9  branch      the mechanical facts about the branch: tree, modes, artifacts, claims
   9  review      a different model attacks the change before it is filed
@@ -92,6 +93,7 @@ case "$cmd" in
   outside)   script=distinct-outside.sh ;;
   prior-art) script=prior-art.sh ;;
   census)    script=comment-census.sh ;;
+  comments)  script=comment-check.sh ;;
   claims)    script=claim-check.sh ;;
   branch)    script=branch-check.sh ;;
   review)    script=review.sh ;;

{housebroken_cli-0.5.0 → housebroken_cli-0.6.0}/pyproject.toml

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

{housebroken_cli-0.5.0 → housebroken_cli-0.6.0}/scripts/branch-check.sh

@@ -1,40 +1,37 @@
 #!/bin/bash
 # branch-check.sh - the mechanical facts about the branch you are about to file.
 #
-# Three defects on PaloAltoNetworks/docusaurus-openapi-docs #1624 were facts
-# about the branch rather than about the patch, and git could have printed all
-# three before anything left the machine.
+# 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). Absolute claims in added
+# prose are printed for you to falsify one by one; some of them are true.
 #
-# A reviewer had just shown that a sentence in the added documentation
-# overclaimed. The wording was corrected in the working tree, the branch was
-# rebuilt with `git reset --soft <base>`, and the commits still carried the old
-# sentence: a soft reset leaves the index at the previous commit, so the
-# corrected file was never staged. The tree was dirty and nobody looked. A
-# dirty tree is a refusal here, because what you tested is not what you file.
-#
-# The new test file was committed 100755 where every other test in that
-# repository is 100644, which GitHub renders in the diff. A mode that disagrees
-# with the file's own siblings is a refusal.
-#
-# The overclaiming sentence was an absolute: "removes only the files the plugin
-# generated", which the code falsifies for two file names. Absolutes in added
-# prose are printed for you to check one by one; they are not refused, because
-# 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]
+#   bash branch-check.sh [CLONE] [--base REF] [--asked URL]
 #   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.
 #
 # 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=""
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --help|-h) usage; exit 0 ;;
@@ -43,6 +40,13 @@ while [ "$#" -gt 0 ]; do
       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=}" ;;
     -*) echo "REFUSED: unknown option $1" >&2; exit 2 ;;
     *) clone="$1" ;;
   esac
@@ -124,27 +128,37 @@ $files
 EOF
 
 # A tool trailer is the one thing in a commit that cannot be argued as style.
-# Thirteen open pull requests across ten organisations were found carrying
-# "Co-Authored-By: Claude ..." and four of them a live claude.ai session URL,
-# on NVIDIA, Microsoft, Apple, Uber, Tesla, Apache and IBM repositories. No
-# project asked for it; a harness adds it by default and nobody read the commit
-# before pushing. The body is checked for this at step 9; the commits were not.
-trailers=$(git log --format='%H %s%n%b' "$base..HEAD" 2>/dev/null \
-  | grep -inE 'Co-Authored-By: *Claude|Claude-Session:|https://claude\.ai/code|Generated with .*Claude')
+# 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, which no project asked for"
+  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, and several projects say so in as many words.
-if git log --format='%b' "$base..HEAD" 2>/dev/null | grep -qE '^Signed-off-by:'; then
-  usernames=$(git log --format='%b' "$base..HEAD" 2>/dev/null | grep -E '^Signed-off-by: [a-z0-9_-]+ <')
-  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
+# 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/^/    /'
+
 # 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/^+//' \
@@ -165,5 +179,9 @@ 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.
+head=$(git rev-parse HEAD)
+mkdir -p "$home/branch-checks"
+printf 'head: %s\nbase: %s\nchecked: %s\n' "$head" "$(git rev-parse "$base")" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$home/branch-checks/$head"
 echo
 echo "branch-check: nothing mechanical blocks this branch."

housebroken_cli-0.6.0/scripts/check-ai-policy.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+# check-ai-policy.sh - read a repository's stance on AI-assisted contributions
+# where it actually lives, and say what it requires.
+#
+# The rule: a project that bans AI-written contributions never gets one; a
+# project that asks for disclosure gets a truthful sentence in the body; a
+# project that says nothing gets nothing. The policy is read from the
+# repository itself, never from a description of it: every file on the branch
+# whose name is a contributing guide, a code of conduct, a pull request or
+# issue template, a README or an agent instruction file, matched without
+# regard to case, plus the same files in the organization's .github
+# repository.
+#
+# Usage:
+#   bash check-ai-policy.sh [--branch <name>] [--out] 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
+#
+# 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.
+#
+# Environment:
+#   HOUSEBROKEN_HOME  work directory, default $HOME/.housebroken; --out writes
+#                     to its policy/ subdirectory, created if missing.
+#
+# Assumes gh is installed and authenticated. Read-only: GET calls only.
+set -u
+
+usage() { awk 'NR>1 && /^#/ {sub(/^# ?/, ""); print; next} NR>1 {exit}' "$0"; }
+
+# Policy files, matched against the repository's own tree listing without
+# 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
+
+# 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'
+BAN_RE='not (be )?(accept|allow|permit|welcome)|prohibit|forbid|banned|\bban\b|will be closed|closed without|do not (use|submit|open)|don.t (use|submit)|refrain from|no (AI|LLM|AI-generated|machine-generated)|must not|may not (use|submit)|are not (allowed|accepted|permitted)|zero tolerance'
+DISCLOSE_RE='disclos|disclaimer|declare|must (state|say|note|indicate|mention)|be transparent|label(l)?ed as|clearly (state|indicate|mark)|acknowledg|(if|whether) (you )?(use|used|using) (AI|an AI|LLM)|which (AI|LLM) tool|AI transcript|used AI to'
+
+branch_opt=""
+out=0
+repos=()
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --help|-h) usage; exit 0 ;;
+    --branch) shift; [ "$#" -gt 0 ] || { echo "check-ai-policy.sh: --branch needs a name" >&2; exit 1; }
+              branch_opt="$1" ;;
+    --branch=*) branch_opt="${1#--branch=}" ;;
+    --out) out=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 ;;
+  esac
+  shift
+done
+[ "${#repos[@]}" -gt 0 ] || { usage >&2; exit 1; }
+
+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}"
+
+# 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.
+scan() {
+  local target="$1" ref="$2" label="$3" f body hits
+  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
+    hits=$(printf '%s' "$body" | grep -nE "$PATTERN" | head -20)
+    if [ -n "$hits" ]; then
+      found=1
+      echo "  --- $label$f ---"
+      printf '%s\n' "$hits" | cut -c1-300 | sed 's/^/      /'
+      printf '%s\n' "$hits" | grep -qiE "$BAN_RE" && ban=1
+      printf '%s\n' "$hits" | grep -qiE "$DISCLOSE_RE" && disclose=1
+    else
+      echo "  (clean) $label$f"
+    fi
+  done < <(policy_files "$target" "$ref")
+}
+
+status=0
+for repo in "${repos[@]}"; do
+  found=0; ban=0; disclose=0
+  report=$(
+    echo "## AI policy: $repo"
+    echo "read: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    branch="$branch_opt"
+    if [ -z "$branch" ]; then
+      branch=$(gh api "repos/$repo" --jq .default_branch 2>/dev/null) || branch=""
+    fi
+    if [ -z "$branch" ]; then
+      echo "ERROR: cannot read $repo from GitHub"
+      exit 1
+    fi
+    echo "branch: $branch"
+    scan "$repo" "$branch" ""
+    org="${repo%%/*}"
+    org_branch=$(gh api "repos/$org/.github" --jq .default_branch 2>/dev/null) || org_branch=""
+    if [ -n "$org_branch" ]; then
+      echo "org repo: $org/.github ($org_branch)"
+      scan "$org/.github" "$org_branch" "$org/.github: "
+    fi
+    if [ "$ban" -eq 1 ]; then echo "RESULT: BAN (a policy file forbids or closes AI-written contributions; never file here)"
+    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)"
+    fi
+  )
+  rc=$?
+  printf '%s\n' "$report"
+  if [ "$rc" -ne 0 ]; then status=1; continue; fi
+  case "$report" in
+    *"RESULT: BAN"*) [ "$status" -lt 4 ] && status=4 ;;
+    *"RESULT: DISCLOSE"*) [ "$status" -lt 3 ] && status=3 ;;
+  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"
+  fi
+done
+exit "$status"

{housebroken_cli-0.5.0 → housebroken_cli-0.6.0}/scripts/claim-check.sh

@@ -2,19 +2,12 @@
 # claim-check.sh - lists every claim in outbound text that a maintainer can
 # falsify, so each one gets re-derived before it is sent.
 #
-# On microsoft/GSL #1272 a reply draft said "The five new static_asserts fail on
-# main." A reviewer falsified it in one pass. The number had come from a red arm
-# that grepped only for `static assertion failed`, so it counted five matches
-# and never saw the twenty-one other errors beside them; and against the commit
-# a maintainer would actually revert to, only four of the five fail. The
-# sentence named a basis and was still wrong about it.
-#
-# So this does not try to judge a claim. Text checks cannot: the bad sentence
-# named its revision and read perfectly. It lists them, and the rule in step 6
-# is that every listed line is re-measured, at the moment of writing, against
-# the exact revision the sentence names. The gap this closes is that until now
-# every gate here read code and nothing read the prose, while the prose is what
-# the maintainer reads first.
+# A count or an absolute in outbound prose is a claim the maintainer can check
+# in one command, and a sentence that names its revision can still be wrong
+# about it. This does not judge a claim, because a text check cannot; it lists
+# every one, and the rule is that each listed line is re-measured, at the
+# moment of writing, against the exact revision the sentence names. The prose
+# is what the maintainer reads first.
 #
 # Usage:
 #   bash claim-check.sh FILE