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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/PKG-INFO +16 -11
  2. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/README.md +15 -10
  3. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/bin/housebroken +6 -0
  4. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/pyproject.toml +1 -1
  5. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/branch-check.sh +111 -12
  6. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/check-ai-policy.sh +80 -19
  7. housebroken_cli-0.8.0/scripts/declare.sh +90 -0
  8. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/file-issue.sh +10 -2
  9. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/file-pr.sh +111 -4
  10. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/fork-hygiene.sh +11 -0
  11. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/prior-art.sh +43 -10
  12. housebroken_cli-0.8.0/scripts/proof.sh +204 -0
  13. housebroken_cli-0.8.0/scripts/ref-check.sh +114 -0
  14. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/review.sh +27 -2
  15. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/verify-filed-pr.sh +30 -0
  16. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/skills/housebroken/SKILL.md +65 -22
  17. housebroken_cli-0.8.0/src/housebroken/__init__.py +1 -0
  18. housebroken_cli-0.6.9/src/housebroken/__init__.py +0 -1
  19. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/.gitignore +0 -0
  20. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/LICENSE +0 -0
  21. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/hatch_build.py +0 -0
  22. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/claim-check.sh +0 -0
  23. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/comment-census.sh +0 -0
  24. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/comment-check.sh +0 -0
  25. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/diff-defaults.sh +0 -0
  26. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/distinct-outside.sh +0 -0
  27. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/inbox.sh +0 -0
  28. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/notes.sh +0 -0
  29. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/pr-sweep.sh +0 -0
  30. {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/src/housebroken/cli.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: housebroken-cli
3
- Version: 0.6.9
3
+ Version: 0.8.0
4
4
  Summary: Agent-written pull requests that do not make a mess in someone else's house.
5
5
  Project-URL: Repository, https://github.com/lenamonj/housebroken
6
6
  License-Expression: MIT
@@ -52,22 +52,22 @@ the CLA known before filing, the SECURITY.md route taken when it applies
52
52
  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).
53
53
 
54
54
  **1. Read the house rules before knocking.**
55
- `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.
55
+ `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.
56
56
 
57
57
  **2. Is it already on the table?**
58
- `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.
58
+ `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.
59
59
 
60
60
  **3. Is it a fix or an opinion?**
61
61
  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.
62
62
 
63
63
  **4. Prove it red first, and prove the proof.**
64
- 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.
64
+ 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. `proof.sh` runs the experiment itself: the test on the head, then on the head with every changed non-test file swapped back to its content at the merge base, then the head restored and checked by hash, and it stamps the head only when the base arm fails and the head arm passes. A change with nothing to show red says so, with the reason, and the filing prints it.
65
65
 
66
66
  **5. Run their CI, not yours.**
67
67
  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.
68
68
 
69
69
  **6. Match the house style.**
70
- `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.
70
+ `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.
71
71
 
72
72
  **7. Know the paperwork.**
73
73
  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
76
76
  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.
77
77
 
78
78
  **9. File through the gate.**
79
- `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.
80
- `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.
81
- `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.
79
+ `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.
80
+ `review.sh` names the adversarial reviewer: a different model from the one that wrote the change, one tier down, never below Sonnet. Before it runs, the author writes a declaration (`declare.sh`): what the change was not tested against, and every assumption with what breaks if it is wrong and how it was checked. "Nothing" is refused as an answer. The review reads the declaration as one of its texts and attacks each line. 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.
81
+ `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 proof stamp for that head, a declaration that passes, a POST AS IS review of that head, that body and that declaration, fewer than three open pull requests of yours on the repository, and ten minutes since the last.
82
82
  `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.
83
83
 
84
84
  **10. Watch it land.**
85
- `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.
85
+ `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.
86
86
 
87
87
  **11. Clean up.**
88
- `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.
88
+ `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.
89
89
 
90
90
  **12. Three per repository, one finding each.**
91
91
  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,10 @@ uv tool install git+https://github.com/lenamonj/housebroken
121
121
  | `scripts/comment-census.sh` | added code versus added comments, per branch |
122
122
  | `scripts/diff-defaults.sh` | default arguments and one-line wrappers added to keep call sites untouched |
123
123
  | `scripts/claim-check.sh` | every falsifiable claim in a body or a reply, listed to re-derive |
124
- | `scripts/branch-check.sh` | the branch's mechanical facts: clean tree, modes, artifacts, trailers, sign-offs, comments, absolute claims |
124
+ | `scripts/proof.sh` | the red-first experiment, run and stamped: red on the base, green on the head |
125
+ | `scripts/declare.sh` | what was not tested and what was assumed, for the review to attack |
126
+ | `scripts/ref-check.sh` | every issue, link, test, file and commit a body names, looked up |
127
+ | `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 |
125
128
  | `scripts/review.sh` | the adversarial review: a different model attacks the change, and the filing is held to exactly what it read |
126
129
  | `scripts/file-pr.sh` | the only way a pull request gets filed: five gates in front of `gh pr create` |
127
130
  | `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 +140,8 @@ The scripts are bash and need `gh` and `jq`. Each script's header says what it a
137
140
 
138
141
  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.
139
142
 
143
+ 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.
144
+
140
145
  ## FAQ
141
146
 
142
147
  **Is this only for AI-written pull requests?**
@@ -40,22 +40,22 @@ the CLA known before filing, the SECURITY.md route taken when it applies
40
40
  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).
41
41
 
42
42
  **1. Read the house rules before knocking.**
43
- `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.
43
+ `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.
44
44
 
45
45
  **2. Is it already on the table?**
46
- `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.
46
+ `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.
47
47
 
48
48
  **3. Is it a fix or an opinion?**
49
49
  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.
50
50
 
51
51
  **4. Prove it red first, and prove the proof.**
52
- 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.
52
+ 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. `proof.sh` runs the experiment itself: the test on the head, then on the head with every changed non-test file swapped back to its content at the merge base, then the head restored and checked by hash, and it stamps the head only when the base arm fails and the head arm passes. A change with nothing to show red says so, with the reason, and the filing prints it.
53
53
 
54
54
  **5. Run their CI, not yours.**
55
55
  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.
56
56
 
57
57
  **6. Match the house style.**
58
- `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.
58
+ `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.
59
59
 
60
60
  **7. Know the paperwork.**
61
61
  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
64
64
  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.
65
65
 
66
66
  **9. File through the gate.**
67
- `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.
68
- `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.
69
- `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.
67
+ `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.
68
+ `review.sh` names the adversarial reviewer: a different model from the one that wrote the change, one tier down, never below Sonnet. Before it runs, the author writes a declaration (`declare.sh`): what the change was not tested against, and every assumption with what breaks if it is wrong and how it was checked. "Nothing" is refused as an answer. The review reads the declaration as one of its texts and attacks each line. 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.
69
+ `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 proof stamp for that head, a declaration that passes, a POST AS IS review of that head, that body and that declaration, fewer than three open pull requests of yours on the repository, and ten minutes since the last.
70
70
  `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.
71
71
 
72
72
  **10. Watch it land.**
73
- `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.
73
+ `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.
74
74
 
75
75
  **11. Clean up.**
76
- `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.
76
+ `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.
77
77
 
78
78
  **12. Three per repository, one finding each.**
79
79
  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,10 @@ uv tool install git+https://github.com/lenamonj/housebroken
109
109
  | `scripts/comment-census.sh` | added code versus added comments, per branch |
110
110
  | `scripts/diff-defaults.sh` | default arguments and one-line wrappers added to keep call sites untouched |
111
111
  | `scripts/claim-check.sh` | every falsifiable claim in a body or a reply, listed to re-derive |
112
- | `scripts/branch-check.sh` | the branch's mechanical facts: clean tree, modes, artifacts, trailers, sign-offs, comments, absolute claims |
112
+ | `scripts/proof.sh` | the red-first experiment, run and stamped: red on the base, green on the head |
113
+ | `scripts/declare.sh` | what was not tested and what was assumed, for the review to attack |
114
+ | `scripts/ref-check.sh` | every issue, link, test, file and commit a body names, looked up |
115
+ | `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 |
113
116
  | `scripts/review.sh` | the adversarial review: a different model attacks the change, and the filing is held to exactly what it read |
114
117
  | `scripts/file-pr.sh` | the only way a pull request gets filed: five gates in front of `gh pr create` |
115
118
  | `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 +128,8 @@ The scripts are bash and need `gh` and `jq`. Each script's header says what it a
125
128
 
126
129
  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.
127
130
 
131
+ 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.
132
+
128
133
  ## FAQ
129
134
 
130
135
  **Is this only for AI-written pull requests?**
@@ -47,10 +47,13 @@ usage: housebroken <subcommand> [args...]
47
47
  1 policy read the repository's AI-contribution policy where it lives
48
48
  1 outside count outside contributors merged in the last 120 days
49
49
  2 prior-art issues and pull requests on the touched files, rulings quoted
50
+ 4 proof run the test on the base and the head, and stamp red then green
50
51
  6 census added code lines against added comment lines, per branch
51
52
  6 comments refuse a comment added to code nobody asked for
52
53
  6 claims every falsifiable claim in outbound text, listed to re-derive
54
+ 6 refs every issue, link, test, file and commit the text names, looked up
53
55
  9 branch the mechanical facts about the branch: tree, modes, artifacts, claims
56
+ 9 declare what was not tested and what was assumed, for the review to attack
54
57
  9 review a different model attacks the change before it is filed
55
58
  9 file the only way a pull request gets filed
56
59
  9 issue the only way an issue gets filed
@@ -96,6 +99,9 @@ case "$cmd" in
96
99
  census) script=comment-census.sh ;;
97
100
  comments) script=comment-check.sh ;;
98
101
  claims) script=claim-check.sh ;;
102
+ refs) script=ref-check.sh ;;
103
+ proof) script=proof.sh ;;
104
+ declare) script=declare.sh ;;
99
105
  branch) script=branch-check.sh ;;
100
106
  review) script=review.sh ;;
101
107
  file) script=file-pr.sh ;;
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "housebroken-cli"
7
- version = "0.6.9"
7
+ version = "0.8.0"
8
8
  description = "Agent-written pull requests that do not make a mess in someone else's house."
9
9
  dynamic = ["readme"]
10
10
  license = "MIT"
@@ -43,6 +43,7 @@ base=""
43
43
  asked=""
44
44
  warnlog=""
45
45
  aotlog=""
46
+ allows=()
46
47
  while [ "$#" -gt 0 ]; do
47
48
  case "$1" in
48
49
  --help|-h) usage; exit 0 ;;
@@ -68,6 +69,11 @@ while [ "$#" -gt 0 ]; do
68
69
  aotlog="${1:-}"
69
70
  [ -f "$aotlog" ] || { echo "REFUSED: --aot-log needs an AOT publish log file" >&2; exit 2; }
70
71
  ;;
72
+ --allow)
73
+ shift
74
+ [ -n "${1:-}" ] || { echo "REFUSED: --allow needs a path" >&2; exit 2; }
75
+ allows+=("$1")
76
+ ;;
71
77
  -*) echo "REFUSED: unknown option $1" >&2; exit 2 ;;
72
78
  *) clone="$1" ;;
73
79
  esac
@@ -87,6 +93,9 @@ git rev-parse --verify -q "$base" >/dev/null 2>&1 || { echo "REFUSED: base $base
87
93
 
88
94
  blocked=0
89
95
  block() { echo "REFUSED: $*"; blocked=1; }
96
+ # Whether the base already carries a path. "rev:path" is not used because Git
97
+ # for Windows' shell rewrites an argument shaped like "a/b:.c/d" as a path list.
98
+ in_base() { [ -n "$(git ls-tree --name-only "$base" -- "$1" 2>/dev/null)" ]; }
90
99
 
91
100
  echo "== branch check: $(git rev-parse --abbrev-ref HEAD) against $base =="
92
101
 
@@ -97,6 +106,21 @@ if [ -n "$dirty" ]; then
97
106
  printf '%s\n' "$dirty" | sed 's/^/ /'
98
107
  fi
99
108
 
109
+ # A base nobody fetched is the upstream as it was, not as it is: ask the remote.
110
+ full=$(git rev-parse --symbolic-full-name "$base" 2>/dev/null)
111
+ case "$full" in
112
+ refs/remotes/*/*)
113
+ rest="${full#refs/remotes/}"; remote="${rest%%/*}"; rbranch="${rest#*/}"
114
+ live=$(git ls-remote "$remote" "refs/heads/$rbranch" 2>/dev/null | awk '{print $1}')
115
+ if [ -z "$live" ]; then
116
+ block "cannot read $rbranch from $remote, so whether $base is current is unknown"
117
+ elif [ "$live" != "$(git rev-parse "$base")" ]; then
118
+ 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"
119
+ fi
120
+ ;;
121
+ *) block "base $base is not a remote-tracking ref, so whether it is current cannot be checked - pass --base <remote>/<branch>" ;;
122
+ esac
123
+
100
124
  if ! git merge-base --is-ancestor "$base" HEAD 2>/dev/null; then
101
125
  block "HEAD is not on top of $base - rebase before filing"
102
126
  fi
@@ -136,16 +160,22 @@ while IFS= read -r f; do
136
160
  # forced. NVIDIA/go-nvml ignores "dl" for a built binary, and that pattern also
137
161
  # matches the directory pkg/dl, so forcing the check called two upstream source
138
162
  # files build output.
139
- if ! git cat-file -e "$base:$f" 2>/dev/null; then
163
+ if ! in_base "$f"; then
140
164
  if git check-ignore -q --no-index -- "$f" 2>/dev/null; then
141
165
  block "$f is added by this branch and the repository's .gitignore excludes it"
142
166
  fi
143
167
  fi
144
168
 
145
169
  case "$f" in
146
- .jeffy/*|*/.jeffy/*|PLAN.md|*/PLAN.md|JOURNAL.md|*/JOURNAL.md|*.orig|*.rej)
170
+ .jeffy/*|*/.jeffy/*|PLAN.md|*/PLAN.md|JOURNAL.md|*/JOURNAL.md|*.orig|*.rej|*.bak|*.swp|.DS_Store|*/.DS_Store|Thumbs.db|*/Thumbs.db)
147
171
  block "$f is a working artifact and has no place in the diff" ;;
148
172
  esac
173
+ # An agent's instruction or scratch file is an artifact when this branch adds
174
+ # it; a project that already keeps one may have it edited.
175
+ case "$f" in
176
+ .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)
177
+ in_base "$f" || block "$f is added by this branch and reads as an agent's working file" ;;
178
+ esac
149
179
  done <<EOF
150
180
  $files
151
181
  EOF
@@ -187,15 +217,27 @@ printf '%s\n' "$comments" | grep -E '^CHECK: ' | sed 's/^/ /'
187
217
  # that is wrong in a way the analyzer cannot see.
188
218
  added=$(git diff -U0 "$base..HEAD" -- . ':(exclude)*.md' ':(exclude)*.rst' ':(exclude)*.txt' 2>/dev/null \
189
219
  | grep '^+' | grep -v '^+++' | sed 's/^+//')
190
- 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')
220
+ 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')
191
221
  if [ -n "$suppressions" ]; then
192
- ids=$(printf '%s\n' "$suppressions" | grep -oE '\b[A-Z]{1,4}[0-9]{3,5}\b' | sort -u)
222
+ # Each suppression names what it hides: a code such as IL2075 or C4996, else
223
+ # the rule names after its keyword (errcheck, no-unused-vars). One that names
224
+ # nothing hides every warning on its line, and no log can show what it covers.
193
225
  unshown=""
194
- if [ -z "$warnlog" ]; then
195
- unshown="no --warning-log given"
196
- else
197
- for id in $ids; do grep -q "$id" "$warnlog" || unshown="$unshown $id"; done
198
- fi
226
+ while IFS= read -r line; do
227
+ [ -n "$line" ] || continue
228
+ ids=$(printf '%s\n' "$line" | grep -oE '\b([A-Za-z]{1,6}[0-9]{3,5}|[0-9]{4})\b' | sort -u)
229
+ if [ -z "$ids" ]; then
230
+ 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/ *(\/\/|#).*//' \
231
+ | grep -oE '[A-Za-z][A-Za-z0-9_-]{2,}' | grep -vxE 'disable|enable|next|line|this' | sort -u)
232
+ fi
233
+ if [ -z "$ids" ]; then
234
+ unshown="$unshown [names no warning: $(printf '%s' "$line" | sed 's/^[[:space:]]*//' | cut -c1-60)]"
235
+ elif [ -z "$warnlog" ]; then
236
+ unshown="$unshown $(printf '%s' "$ids" | tr '\n' ' ')(no --warning-log given)"
237
+ else
238
+ for id in $ids; do grep -qF -- "$id" "$warnlog" || unshown="$unshown $id"; done
239
+ fi
240
+ done <<< "$suppressions"
199
241
  if [ -n "$unshown" ]; then
200
242
  block "the branch adds a warning suppression, and no build log shows the warning firing ($unshown)"
201
243
  printf '%s\n' "$suppressions" | sed 's/^/ /'
@@ -209,12 +251,67 @@ aotdecl=$(git grep -lE '<(IsAotCompatible|IsTrimmable|PublishAot|EnableTrimAnaly
209
251
  if [ -n "$aotdecl" ]; then
210
252
  reflection=$(git diff -U0 "$base..HEAD" -- '*.cs' 2>/dev/null | grep '^+' | grep -v '^+++' | sed 's/^+//' \
211
253
  | grep -E '\.Get(Property|Properties|Method|Methods|Field|Fields|Member|Members|Interfaces)\(|Activator\.CreateInstance|MakeGenericType|MakeGenericMethod|Type\.GetType\(|\.InvokeMember\(')
212
- if [ -n "$reflection" ] && ! { [ -n "$aotlog" ] && grep -q "Generating native code" "$aotlog"; }; then
213
- block "the branch adds reflection to a project that declares AOT or trim support (${aotdecl% }), and no --aot-log shows an AOT publish"
254
+ # The log has to be a publish of this repository: it names, as a word, a
255
+ # declaring project, or any project here when the declaration is in a .props.
256
+ published=0
257
+ if [ -n "$aotlog" ] && grep -q "Generating native code" "$aotlog"; then
258
+ for p in $aotdecl; do
259
+ case "$p" in
260
+ *.csproj) projs=$(basename "$p" .csproj) ;;
261
+ *) projs=$(git ls-files '*.csproj' | sed 's#.*/##; s/\.csproj$//') ;;
262
+ esac
263
+ for proj in $projs; do grep -qwF -- "$proj" "$aotlog" && published=1; done
264
+ done
265
+ fi
266
+ if [ -n "$reflection" ] && [ "$published" -eq 0 ]; then
267
+ 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"
214
268
  printf '%s\n' "$reflection" | sed 's/^/ /'
215
269
  fi
216
270
  fi
217
271
 
272
+ # What embarrasses a contributor first, file by file: a secret or a personal
273
+ # path in an added line, a lockfile or generated file, a binary, and a file
274
+ # rewritten for its line endings or whitespace. --allow PATH names a file the
275
+ # change really is about, such as a dependency bump's lockfile.
276
+ allowed() { local a; for a in ${allows[@]+"${allows[@]}"}; do [ "$1" = "$a" ] && return 0; done; return 1; }
277
+ # A credential anywhere is refused, and so is a path under this user's own
278
+ # home; a path under another user's is a fixture or an example, and is noted.
279
+ me=$(basename "${HOME:-/nobody}")
280
+ 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/"
281
+ path_re='[A-Za-z]:[\\/]Users[\\/][^\\/ ]+|/home/[a-z][a-z0-9_-]*/|/Users/[A-Za-z][^/ ]*/|/mnt/[a-z]/Users/'
282
+ nfiles=0; nadded=0
283
+ while IFS= read -r f; do
284
+ [ -n "$f" ] || continue
285
+ nfiles=$((nfiles + 1))
286
+ stat=$(git diff --numstat "$base..HEAD" -- "$f" | head -1)
287
+ case "$f" in *test*|*spec*) ;; *) nadded=$((nadded + $(printf '%s' "$stat" | awk '{print ($1 == "-") ? 0 : $1}'))) ;; esac
288
+ allowed "$f" && continue
289
+ addedf=$(git diff -U0 "$base..HEAD" -- "$f" | grep '^+' | grep -v '^+++')
290
+ leaks=$(printf '%s\n' "$addedf" | grep -oE "$leak_re" | sort -u)
291
+ [ -z "$leaks" ] || block "$f adds a personal path or a credential: $(printf '%s' "$leaks" | tr '\n' ' ')"
292
+ paths=$(printf '%s\n' "$addedf" | grep -oE "$path_re" | sort -u)
293
+ [ -z "$paths" ] || echo "CHECK: $f adds a user path, a fixture or an example unless it is yours: $(printf '%s' "$paths" | tr '\n' ' ')"
294
+ case "$f" in
295
+ 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)
296
+ block "$f is a lockfile, vendored or generated file - a build rewrote it, or pass --allow $f if the change is about it" ;;
297
+ esac
298
+ case "$stat" in
299
+ -*) block "$f is binary - pass --allow $f if the change needs it" ;;
300
+ *)
301
+ total=$(printf '%s' "$stat" | awk '{print $1 + $2}')
302
+ real=$(git diff --numstat --ignore-space-at-eol --ignore-cr-at-eol "$base..HEAD" -- "$f" | awk '{print $1 + $2}')
303
+ if [ "$total" -ge 10 ] && [ $((${real:-0} * 2)) -lt "$total" ]; then
304
+ block "$f changes $total lines, of which ${real:-0} differ beyond whitespace and line endings - restore the file's own endings"
305
+ fi
306
+ ;;
307
+ esac
308
+ done <<EOF
309
+ $files
310
+ EOF
311
+ if [ "$nfiles" -gt 4 ] || [ "$nadded" -gt 150 ]; then
312
+ echo "CHECK: $nfiles files and $nadded added lines outside tests - one finding, the smallest diff that fixes it"
313
+ fi
314
+
218
315
  # Absolutes in added prose are the claims a maintainer can falsify in one grep.
219
316
  claims=$(git diff -U0 "$base..HEAD" -- '*.md' '*.mdx' '*.rst' '*.txt' 2>/dev/null \
220
317
  | grep '^+' | grep -v '^+++' | sed 's/^+//' \
@@ -235,9 +332,11 @@ if [ "$blocked" -ne 0 ]; then
235
332
  echo "branch-check: refused. Fix the causes above; a refusal is a result."
236
333
  exit 1
237
334
  fi
238
- # The stamp file-pr.sh reads: this head passed, against this base, at this time.
335
+ # The stamp file-pr.sh reads: this head passed, against this base, at this
336
+ # time, changing these files.
239
337
  head=$(git rev-parse HEAD)
240
338
  mkdir -p "$home/branch-checks"
241
339
  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"
340
+ printf '%s\n' "$files" | sed '/^$/d; s/^/file: /' >> "$home/branch-checks/$head"
242
341
  echo
243
342
  echo "branch-check: nothing mechanical blocks this branch."
@@ -12,21 +12,29 @@
12
12
  # repository.
13
13
  #
14
14
  # Usage:
15
- # bash check-ai-policy.sh [--branch <name>] [--out] owner/repo [owner/repo ...]
15
+ # bash check-ai-policy.sh [--branch <name>] [--out] [--accept-truncated] owner/repo [owner/repo ...]
16
16
  # bash check-ai-policy.sh --help
17
17
  #
18
18
  # --branch <name> read this branch instead of the default; some projects
19
19
  # keep the policy on a development branch
20
20
  # --out also save the printout to $HOUSEBROKEN_HOME/policy/
21
- # policy-<owner>-<repo>.md, which file-pr.sh reads
21
+ # policy-<owner>-<repo>.md, which file-pr.sh reads, and
22
+ # the pull request template to template-<owner>-<repo>.md,
23
+ # whose lines file-pr.sh leaves out of the body's word count
24
+ # --accept-truncated read a repository whose tree GitHub truncates (over
25
+ # 100,000 entries) after its policy was read by hand; the
26
+ # printout records that it was
22
27
  #
23
28
  # Every hit is printed with its file and line so the sentence is read, not a
24
29
  # verdict. The RESULT line is the reading: BAN when a sentence forbids or
25
30
  # closes AI-written contributions, DISCLOSE when a sentence requires that AI
26
31
  # use be disclosed, MENTION when AI is named without either, CLEAN when no
27
- # policy file names it. Exit 0 for CLEAN or MENTION, 3 for DISCLOSE, 4 for BAN,
28
- # 1 when the repository cannot be read. With several repositories the exit is
29
- # the highest.
32
+ # policy file names it, UNREAD when GitHub refused, throttled or truncated any
33
+ # listing or file, so a failure is never read as silence. Every policy-named
34
+ # file is read; READMEs are capped at 40 per repository and the cap is printed.
35
+ # Exit 0 for CLEAN or MENTION, 1 for UNREAD or when the repository cannot be
36
+ # read, 3 for DISCLOSE, 4 for BAN. With several repositories the exit is the
37
+ # highest.
30
38
  #
31
39
  # Environment:
32
40
  # HOUSEBROKEN_HOME work directory, default $HOME/.housebroken; --out writes
@@ -41,7 +49,7 @@ usage() { awk 'NR>1 && /^#/ {sub(/^# ?/, ""); print; next} NR>1 {exit}' "$0"; }
41
49
  # regard to case, so CONTRIBUTING.rst, contributing.md and Contributing.md
42
50
  # are all read.
43
51
  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)$'
44
- MAX_FILES=40
52
+ MAX_READMES=40
45
53
 
46
54
  # The word itself, plus its usual spellings and the tools by name.
47
55
  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
50
58
 
51
59
  branch_opt=""
52
60
  out=0
61
+ accept_truncated=0
53
62
  repos=()
54
63
  while [ "$#" -gt 0 ]; do
55
64
  case "$1" in
@@ -58,6 +67,7 @@ while [ "$#" -gt 0 ]; do
58
67
  branch_opt="$1" ;;
59
68
  --branch=*) branch_opt="${1#--branch=}" ;;
60
69
  --out) out=1 ;;
70
+ --accept-truncated) accept_truncated=1 ;;
61
71
  --*) usage >&2; echo "check-ai-policy.sh: unknown option $1" >&2; exit 1 ;;
62
72
  */*) repos+=("$1") ;;
63
73
  *) usage >&2; echo "check-ai-policy.sh: '$1' is not owner/repo" >&2; exit 1 ;;
@@ -68,20 +78,50 @@ done
68
78
 
69
79
  command -v gh >/dev/null 2>&1 || { echo "check-ai-policy.sh: gh is not on PATH" >&2; exit 1; }
70
80
  home="${HOUSEBROKEN_HOME:-$HOME/.housebroken}"
81
+ errfile=$(mktemp)
82
+ tmpl_repo=$(mktemp)
83
+ tmpl_org=$(mktemp)
84
+ trap 'rm -f "$errfile" "$tmpl_repo" "$tmpl_org"' EXIT
71
85
 
72
- # List the policy files at one ref of one repository, from its tree listing.
73
- policy_files() {
74
- gh api "repos/$1/git/trees/$2?recursive=1" --jq '.tree[] | select(.type == "blob") | .path' 2>/dev/null \
75
- | grep -Ei "$NAME_RE" | head -"$MAX_FILES"
76
- }
77
-
78
- # Print every hit in one repository at one ref; sets found, ban, disclose.
86
+ # Print every hit in one repository at one ref; sets found, ban, disclose,
87
+ # and counts what GitHub would not give us in unread and truncated, so a
88
+ # failed or throttled call is never read as a clean file.
79
89
  scan() {
80
- local target="$1" ref="$2" label="$3" f body hits
90
+ local target="$1" ref="$2" label="$3" f body hits tree listed files readmes
91
+ if ! tree=$(gh api "repos/$target/git/trees/$ref?recursive=1" 2>"$errfile"); then
92
+ # An empty repository answers 409: it has no files, so no policy to read.
93
+ if grep -q "409" "$errfile"; then
94
+ echo " (empty) $label$target"
95
+ return
96
+ fi
97
+ echo " UNREAD: the file listing of $target@$ref"
98
+ unread=$((unread + 1))
99
+ return
100
+ fi
101
+ if [ "$(printf '%s' "$tree" | jq -r '.truncated')" = "true" ]; then
102
+ echo " TRUNCATED: GitHub listed only part of the tree of $target@$ref"
103
+ truncated=1
104
+ fi
105
+ listed=$(printf '%s' "$tree" | jq -r '.tree[] | select(.type == "blob") | .path' | grep -Ei "$NAME_RE")
106
+ # Every policy-named file is read; only READMEs, which monorepos carry by the
107
+ # hundred, are capped, and the cap is printed.
108
+ readmes=$(printf '%s\n' "$listed" | grep -iE '(^|/)readme\.[a-z]+$')
109
+ files=$( { printf '%s\n' "$listed" | grep -viE '(^|/)readme\.[a-z]+$'
110
+ printf '%s\n' "$readmes" | head -"$MAX_READMES"; } | grep -v '^$')
111
+ if [ "$(printf '%s\n' "$readmes" | grep -c .)" -gt "$MAX_READMES" ]; then
112
+ echo " (only the first $MAX_READMES of $(printf '%s\n' "$readmes" | grep -c .) READMEs in $label${target} were read)"
113
+ fi
81
114
  while IFS= read -r f; do
82
115
  [ -n "$f" ] || continue
83
- body=$(gh api "repos/$target/contents/$f?ref=$ref" --jq '.content' 2>/dev/null | base64 -d 2>/dev/null)
84
- [ -n "$body" ] || continue
116
+ if ! body=$(gh api "repos/$target/contents/$f?ref=$ref" --jq '.content' 2>/dev/null); then
117
+ echo " UNREAD: $label$f"
118
+ unread=$((unread + 1))
119
+ continue
120
+ fi
121
+ body=$(printf '%s' "$body" | base64 -d 2>/dev/null)
122
+ if printf '%s' "$f" | grep -qiE '(^|/)pull_request_template'; then
123
+ printf '%s\n' "$body" >> "$tmplout"
124
+ fi
85
125
  hits=$(printf '%s' "$body" | grep -nE "$PATTERN" | head -20)
86
126
  if [ -n "$hits" ]; then
87
127
  found=1
@@ -92,12 +132,13 @@ scan() {
92
132
  else
93
133
  echo " (clean) $label$f"
94
134
  fi
95
- done < <(policy_files "$target" "$ref")
135
+ done <<< "$files"
96
136
  }
97
137
 
98
138
  status=0
99
139
  for repo in "${repos[@]}"; do
100
- found=0; ban=0; disclose=0
140
+ found=0; ban=0; disclose=0; unread=0; truncated=0
141
+ : > "$tmpl_repo"; : > "$tmpl_org"
101
142
  report=$(
102
143
  echo "## AI policy: $repo"
103
144
  echo "read: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
@@ -110,14 +151,26 @@ for repo in "${repos[@]}"; do
110
151
  exit 1
111
152
  fi
112
153
  echo "branch: $branch"
154
+ tmplout="$tmpl_repo"
113
155
  scan "$repo" "$branch" ""
114
156
  org="${repo%%/*}"
115
- org_branch=$(gh api "repos/$org/.github" --jq .default_branch 2>/dev/null) || org_branch=""
157
+ # A missing .github repository is a 404; any other failure is a policy we did not read.
158
+ if ! org_branch=$(gh api "repos/$org/.github" --jq .default_branch 2>"$errfile"); then
159
+ org_branch=""
160
+ grep -q "404" "$errfile" || { echo " UNREAD: $org/.github"; unread=$((unread + 1)); }
161
+ fi
116
162
  if [ -n "$org_branch" ]; then
117
163
  echo "org repo: $org/.github ($org_branch)"
164
+ tmplout="$tmpl_org"
118
165
  scan "$org/.github" "$org_branch" "$org/.github: "
119
166
  fi
167
+ if [ "$truncated" -eq 1 ] && [ "$accept_truncated" -eq 1 ]; then
168
+ echo "truncated tree accepted by --accept-truncated: files GitHub did not list were not read"
169
+ truncated=0
170
+ fi
120
171
  if [ "$ban" -eq 1 ]; then echo "RESULT: BAN (a policy file forbids or closes AI-written contributions; never file here)"
172
+ elif [ "$unread" -gt 0 ]; then echo "RESULT: UNREAD ($unread policy file(s) or listing(s) could not be fetched; rerun when GitHub answers)"
173
+ elif [ "$truncated" -eq 1 ]; then echo "RESULT: UNREAD (GitHub truncated the file listing; read the policy by hand, then rerun with --accept-truncated)"
121
174
  elif [ "$disclose" -eq 1 ]; then echo "RESULT: DISCLOSE (a policy file requires AI use to be disclosed; say so in the body)"
122
175
  elif [ "$found" -eq 1 ]; then echo "RESULT: MENTION (a policy file names AI; read the lines above and decide)"
123
176
  else echo "RESULT: CLEAN (no policy file names AI)"
@@ -129,11 +182,19 @@ for repo in "${repos[@]}"; do
129
182
  case "$report" in
130
183
  *"RESULT: BAN"*) [ "$status" -lt 4 ] && status=4 ;;
131
184
  *"RESULT: DISCLOSE"*) [ "$status" -lt 3 ] && status=3 ;;
185
+ *"RESULT: UNREAD"*) [ "$status" -lt 1 ] && status=1 ;;
132
186
  esac
133
187
  if [ "$out" -eq 1 ]; then
134
188
  mkdir -p "$home/policy"
135
189
  printf '%s\n' "$report" > "$home/policy/policy-${repo%%/*}-${repo##*/}.md"
136
190
  echo "saved: $home/policy/policy-${repo%%/*}-${repo##*/}.md"
191
+ # The pull request template, the repository's own or else its
192
+ # organization's, is what file-pr.sh leaves out of the body's word count.
193
+ template="$home/policy/template-${repo%%/*}-${repo##*/}.md"
194
+ if [ -s "$tmpl_repo" ]; then cp "$tmpl_repo" "$template"
195
+ elif [ -s "$tmpl_org" ]; then cp "$tmpl_org" "$template"
196
+ else rm -f "$template"
197
+ fi
137
198
  fi
138
199
  done
139
200
  exit "$status"