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.
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/PKG-INFO +16 -11
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/README.md +15 -10
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/bin/housebroken +6 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/pyproject.toml +1 -1
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/branch-check.sh +111 -12
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/check-ai-policy.sh +80 -19
- housebroken_cli-0.8.0/scripts/declare.sh +90 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/file-issue.sh +10 -2
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/file-pr.sh +111 -4
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/fork-hygiene.sh +11 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/prior-art.sh +43 -10
- housebroken_cli-0.8.0/scripts/proof.sh +204 -0
- housebroken_cli-0.8.0/scripts/ref-check.sh +114 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/review.sh +27 -2
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/verify-filed-pr.sh +30 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/skills/housebroken/SKILL.md +65 -22
- housebroken_cli-0.8.0/src/housebroken/__init__.py +1 -0
- housebroken_cli-0.6.9/src/housebroken/__init__.py +0 -1
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/.gitignore +0 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/LICENSE +0 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/hatch_build.py +0 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/claim-check.sh +0 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/comment-census.sh +0 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/comment-check.sh +0 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/diff-defaults.sh +0 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/distinct-outside.sh +0 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/inbox.sh +0 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/notes.sh +0 -0
- {housebroken_cli-0.6.9 → housebroken_cli-0.8.0}/scripts/pr-sweep.sh +0 -0
- {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.
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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/
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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/
|
|
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 ;;
|
|
@@ -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 !
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
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
|
-
|
|
213
|
-
|
|
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
|
|
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
|
|
28
|
-
#
|
|
29
|
-
# the
|
|
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
|
-
|
|
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
|
-
#
|
|
73
|
-
|
|
74
|
-
|
|
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
|
|
84
|
-
|
|
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
|
|
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
|
-
|
|
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"
|