housebroken-cli 0.1.0__py3-none-any.whl

housebroken/scripts/pr-sweep.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# pr-sweep.sh - every open upstream PR of ours, and which ones need us to act.
+#
+# Every maintainer comment gets a same-day answer; without a sweep the answer
+# depends on remembering which PR was touched. Ball in our court means any of:
+# the newest comment or review is not ours (bots excluded), a review requests
+# changes, CI has a failing check, or the PR is CONFLICTING (needs a rebase).
+# Read-only; acting is the operator's.
+#
+# Usage:
+#   bash pr-sweep.sh            # prints only PRs where the ball is in our court
+#   bash pr-sweep.sh --all      # prints every open PR with its state
+#   bash pr-sweep.sh --help
+#
+# Environment:
+#   HOUSEBROKEN_USER  GitHub login to sweep, default the authenticated user
+#
+# Assumes: gh is installed and authenticated, and that the PRs of interest are
+# the ones authored by that login. Exits non-zero when gh fails or the search
+# returns nothing.
+set -u
+
+usage() {
+  sed -n '2,/^set -u$/p' "$0" | sed 's/^# \{0,1\}//; /^set -u$/d'
+}
+
+ALL=0
+case "${1:-}" in
+  --help|-h) usage; exit 0 ;;
+  --all) ALL=1 ;;
+  "") ;;
+  *) echo "pr-sweep.sh: unknown argument: $1" >&2; usage >&2; exit 2 ;;
+esac
+
+ME="${HOUSEBROKEN_USER:-$(gh api user --jq .login)}"
+if [ -z "$ME" ]; then
+  echo "pr-sweep.sh: cannot determine the GitHub login; set HOUSEBROKEN_USER" >&2
+  exit 1
+fi
+
+if ! list="$(gh search prs --author "$ME" --state open --limit 100 --json repository,number,title,updatedAt \
+  --jq '.[] | "\(.repository.nameWithOwner)\t\(.number)\t\(.updatedAt)\t\(.title)"' | sort)"; then
+  echo "pr-sweep.sh: gh search prs failed for author $ME" >&2
+  exit 1
+fi
+[ -n "$list" ] || { echo "pr-sweep.sh: no open PRs found for $ME" >&2; exit 1; }
+n=0; act=0
+while IFS=$'\t' read -r repo num updated title; do
+  [ -n "$repo" ] || continue
+  n=$((n + 1))
+  if ! j="$(gh pr view "$num" --repo "$repo" --json mergeable,reviewDecision,statusCheckRollup,comments,reviews,latestReviews)"; then
+    printf '%-40s #%-5s (gh pr view failed)\n' "$repo" "$num" >&2
+    continue
+  fi
+  last_actor="$(printf '%s' "$j" | jq -r '
+    [ (.comments[]? | {a: .author.login, t: .createdAt}), (.reviews[]? | {a: .author.login, t: .submittedAt}) ]
+    | map(select(.a != null and (.a | test("bot|\\[bot\\]|github-actions|codecov|dependabot|cla-|-cla|claassistant|coderabbit|devin|coveralls|vercel|asf-|apache-"; "i") | not)))
+    | sort_by(.t) | last | "\(.a // "-") \(.t // "-")"')"
+  la_user="${last_actor%% *}"; la_time="${last_actor#* }"
+  ci="$(printf '%s' "$j" | jq -r '[.statusCheckRollup[]? | (.conclusion // .state // "PENDING")] | if length == 0 then "none" elif any(. == "FAILURE" or . == "ERROR") then "FAILING" elif any(. == "PENDING" or . == "IN_PROGRESS" or . == "QUEUED" or . == "EXPECTED") then "pending" else "green" end')"
+  mergeable="$(printf '%s' "$j" | jq -r '.mergeable // "-"')"
+  decision="$(printf '%s' "$j" | jq -r '.reviewDecision // "-"')"
+  why=""
+  [ "$la_user" != "-" ] && [ "$la_user" != "$ME" ] && why="$why last-word:$la_user@${la_time:0:10}"
+  [ "$decision" = "CHANGES_REQUESTED" ] && why="$why changes-requested"
+  [ "$ci" = "FAILING" ] && why="$why ci-failing"
+  [ "$mergeable" = "CONFLICTING" ] && why="$why conflicting"
+  if [ -n "$why" ]; then
+    act=$((act + 1))
+    printf 'ACT  %-38s #%-5s %s  [%s] %s\n' "$repo" "$num" "${title:0:60}" "${why# }" "https://github.com/$repo/pull/$num"
+  elif [ "$ALL" = 1 ]; then
+    printf 'ok   %-38s #%-5s %s  ci=%s mergeable=%s updated=%s\n' "$repo" "$num" "${title:0:60}" "$ci" "$mergeable" "${updated:0:10}"
+  fi
+done <<< "$list"
+echo "open PRs: $n; needing action: $act"

housebroken/scripts/prior-art.sh

@@ -0,0 +1,149 @@
+#!/bin/bash
+# prior-art.sh - list every prior issue and PR on a repo that touches a term,
+# before a PR is written, so the duplicate check is a printout and not a memory.
+#
+# Two PRs were closed as duplicates because this was done by hand. typer #1946
+# (closed 2026-08-31) duplicated OPEN PR typer #1881: gh search issues returns
+# issues and PRs mixed and the type was never checked, so this script prints the
+# type from the API field and never infers it. swift-http-types #153 (closed
+# 2026-09-04) argued against a ruling already made in CLOSED issue #98, which
+# nobody read, so this script prints the last non-author comment on every closed
+# item. A term containing a slash or a dot is treated as a file path and the
+# commit history of that path is scanned for the PRs that touched it.
+# Written 2026-09-07.
+#
+# Usage:
+#   bash prior-art.sh owner/repo <term> [<term> ...] [--out]
+#   bash prior-art.sh --help
+#
+#   --out  also save the printout to $HOUSEBROKEN_HOME/prior-art/, where
+#          file-pr.sh looks for it before it will file anything.
+#
+# Environment:
+#   HOUSEBROKEN_HOME  work directory, default $HOME/.housebroken. --out writes
+#                     to its prior-art/ subdirectory, created if missing.
+#
+# Assumes gh is installed and authenticated, and jq is on PATH. Read-only: it
+# makes GET calls and writes nothing to GitHub.
+set -u
+
+usage() {
+  cat <<'EOF'
+usage: prior-art.sh owner/repo <term>... [--out]
+       prior-art.sh --help
+
+  owner/repo  the upstream repository to search
+  <term>      a symbol, phrase or file path; a term with a slash or a dot is
+              also treated as a path and its commit history is scanned
+  --out       save the printout under $HOUSEBROKEN_HOME/prior-art/
+
+environment:
+  HOUSEBROKEN_HOME  work directory, default $HOME/.housebroken
+EOF
+}
+
+for arg in "$@"; do
+  if [ "$arg" = "--help" ] || [ "$arg" = "-h" ]; then usage; exit 0; fi
+done
+
+command -v gh >/dev/null 2>&1 || { echo "prior-art.sh: gh is not on PATH" >&2; exit 1; }
+command -v jq >/dev/null 2>&1 || { echo "prior-art.sh: jq is not on PATH" >&2; exit 1; }
+
+repo=""
+out=0
+terms=()
+for arg in "$@"; do
+  case "$arg" in
+    --out) out=1 ;;
+    --*) usage >&2; echo "prior-art.sh: unknown option $arg" >&2; exit 1 ;;
+    */*) if [ -z "$repo" ]; then repo="$arg"; else terms+=("$arg"); fi ;;
+    *) if [ -z "$repo" ]; then usage >&2; exit 1; fi
+       terms+=("$arg") ;;
+  esac
+done
+if [ -z "$repo" ] || [ "${#terms[@]}" -eq 0 ]; then
+  usage >&2; exit 1
+fi
+
+home="${HOUSEBROKEN_HOME:-$HOME/.housebroken}"
+calls=0
+items=0
+tmp=$(mktemp) || { echo "prior-art.sh: cannot create temp file" >&2; exit 1; }
+row=$(mktemp) || { echo "prior-art.sh: cannot create temp file" >&2; exit 1; }
+trap 'rm -f "$tmp" "$row"' EXIT
+
+# last comment on a closed item written by somebody other than its author
+last_word() {
+  local num="$1" author="$2" body
+  body=$(gh api "repos/$repo/issues/$num/comments?per_page=100" 2>/dev/null |
+    jq -r --arg a "$author" '[.[] | select(.user.login != $a)] | last | .body // ""') || return 0
+  printf '%s' "$body" | tr '\n\r\t|' '    ' | tr -s ' ' | cut -c1-160
+}
+
+emit() {
+  local kind num state date author title word=""
+  while IFS=$'\t' read -r kind num state date author title; do
+    [ -n "$num" ] || continue
+    word=""
+    if [ "$state" = "closed" ]; then word=$(last_word "$num" "$author"); calls=$((calls+1)); fi
+    printf '| %s | #%s | %s | %s | %s | %s | %s |\n' \
+      "$kind" "$num" "$state" "$date" "$author" "$title" "$word" >>"$tmp"
+    items=$((items+1))
+  done <"$row"
+}
+
+printf '## Prior art: %s (%s)\n' "$repo" "$(date '+%Y-%m-%d %H:%M %Z')" >"$tmp"
+
+for term in "${terms[@]}"; do
+  {
+    printf '\n### %s\n\n' "$term"
+    printf '| type | number | state | date | author | title | last maintainer word |\n'
+    printf '| --- | --- | --- | --- | --- | --- | --- |\n'
+  } >>"$tmp"
+
+  gh api -X GET search/issues -f q="repo:$repo type:issue \"$term\"" -F per_page=10 \
+    --jq '.items[] | ["issue", (.number|tostring), .state, ((.closed_at // .created_at)[0:10]),
+          .user.login, (.title|gsub("[|]";"/")|gsub("[\n\r\t]";" "))] | @tsv' >"$row" ||
+    { echo "prior-art.sh: issue search failed for $repo term '$term'" >&2; exit 1; }
+  calls=$((calls+1))
+  emit
+
+  gh api -X GET search/issues -f q="repo:$repo type:pr \"$term\"" -F per_page=10 \
+    --jq '.items[] | ["PR", (.number|tostring),
+          (if .pull_request.merged_at then "merged" else .state end),
+          ((.pull_request.merged_at // .closed_at // .created_at)[0:10]),
+          .user.login, (.title|gsub("[|]";"/")|gsub("[\n\r\t]";" "))] | @tsv' >"$row" ||
+    { echo "prior-art.sh: PR search failed for $repo term '$term'" >&2; exit 1; }
+  calls=$((calls+1))
+  emit
+
+  # a path term also gets the PRs whose merge commits touched that path
+  case "$term" in
+    */*|*.*)
+      gh api "repos/$repo/commits?path=$term&per_page=30" \
+        --jq '.[] | [(.commit.message|split("\n")[0]|gsub("[|]";"/")),
+              (.commit.author.date[0:10]), (.author.login // .commit.author.name)] | @tsv' \
+        2>/dev/null >"$row" || true
+      calls=$((calls+1))
+      while IFS=$'\t' read -r subject date author; do
+        num=$(printf '%s' "$subject" | grep -oE '#[0-9]+' | head -1 | tr -d '#')
+        [ -n "${num:-}" ] || continue
+        grep -q "^| PR | #$num |" "$tmp" && continue
+        printf '| PR | #%s | merged | %s | %s | %s |  |\n' "$num" "$date" "$author" "$subject" >>"$tmp"
+        items=$((items+1))
+      done <"$row"
+      ;;
+  esac
+done
+
+printf '\n%d items across %d terms. Read every closed item before filing; this script lists, it does not judge.\n' \
+  "$items" "${#terms[@]}" >>"$tmp"
+printf 'gh calls: %d\n' "$calls" >>"$tmp"
+
+cat "$tmp"
+if [ "$out" -eq 1 ]; then
+  dir="$home/prior-art"
+  mkdir -p "$dir" || { echo "prior-art.sh: cannot create $dir" >&2; exit 1; }
+  cp "$tmp" "$dir/prior-art-${repo%%/*}-${repo##*/}.md" ||
+    { echo "prior-art.sh: cannot write $dir/prior-art-${repo%%/*}-${repo##*/}.md" >&2; exit 1; }
+fi

housebroken/scripts/verify-filed-pr.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+# verify-filed-pr.sh - prove a filed PR actually landed as intended.
+#
+# Filing is not the end of the job. This re-derives, from GitHub rather than
+# from local memory, that: the PR head is the commit meant to be there, the
+# diff contains exactly the intended files, CI settled green, and the rendered
+# body and comments are what was written. Written 2026-09-01 after console
+# PR #296 went red on CI and the maintainer saw it before the author did.
+# The check wait was added 2026-09-02, when Valinor #838 was left at "still
+# running" and its mutation job failed unseen.
+#
+# Usage:
+#   bash verify-filed-pr.sh owner/repo PR_NUMBER [expected-head-sha]
+#   bash verify-filed-pr.sh --help
+#
+# Environment:
+#   none
+#
+# Assumes: gh is installed and authenticated with read access to the repo, and
+# that the caller knows which head sha and which files were intended. Exits
+# non-zero when the head does not match, when checks are red, or when they do
+# not settle before the watch gives up.
+set -u
+
+usage() {
+  sed -n '2,/^set -u$/p' "$0" | sed 's/^# \{0,1\}//; /^set -u$/d'
+}
+
+case "${1:-}" in
+  --help|-h) usage; exit 0 ;;
+esac
+
+if [ "$#" -lt 2 ]; then
+  echo "usage: verify-filed-pr.sh owner/repo PR [sha]" >&2
+  exit 2
+fi
+repo="$1"
+pr="$2"
+want="${3:-}"
+fail=0
+note() { printf '%-26s %s\n' "$1" "$2"; }
+
+view() {
+  local field="$1" jqexpr="$2"
+  if ! gh pr view "$pr" --repo "$repo" --json "$field" --jq "$jqexpr"; then
+    echo "verify-filed-pr.sh: gh pr view $repo#$pr ($field) failed" >&2
+    exit 1
+  fi
+}
+
+state=$(view state .state)
+head=$(view headRefOid .headRefOid)
+note "state" "$state"
+note "head" "${head:0:12}"
+if [ -n "$want" ]; then
+  case "$head" in
+    "$want"*) note "head matches expected" "yes" ;;
+    *) note "HEAD MISMATCH" "expected $want"; fail=1 ;;
+  esac
+fi
+
+echo ""
+echo "-- files in the PR (what a reviewer sees)"
+view files '.files[] | "   " + .path + "  +" + (.additions|tostring) + "/-" + (.deletions|tostring)'
+
+echo ""
+echo "-- checks (waits until every check has settled)"
+gh pr checks "$pr" --repo "$repo" --watch --interval 20 >/dev/null 2>&1 || true
+rollup=$(view statusCheckRollup '[.statusCheckRollup[] | (.conclusion // .status)] | group_by(.) | map({k:.[0], n:length}) | .[] | .k + "=" + (.n|tostring)')
+if [ -z "$rollup" ]; then
+  note "checks" "none reported"
+else
+  echo "$rollup" | awk '{print "   " $0}'
+  case "$rollup" in
+    *FAILURE*|*TIMED_OUT*|*CANCELLED*|*ACTION_REQUIRED*) note "CHECKS NOT GREEN" "read the logs"; fail=1 ;;
+    *IN_PROGRESS*|*QUEUED*|*PENDING*) note "CHECKS DID NOT SETTLE" "watch timed out"; fail=1 ;;
+  esac
+fi
+
+echo ""
+echo "-- rendered body, first 15 lines"
+view body .body | head -15 | sed 's/^/   /'
+
+echo ""
+echo "-- comments, newest last"
+view comments '.comments[] | "   " + .author.login + ": " + (.body | gsub("\n"; " ") | .[0:150])'
+
+echo ""
+if [ "$fail" -eq 0 ]; then echo "PR-VERIFY: OK"; else echo "PR-VERIFY: PROBLEMS ABOVE"; fi
+exit "$fail"

housebroken/skill/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: housebroken
+description: >
+  The door every pull request to a repository you do not own must pass
+  through before it is opened, and the manners it keeps after. Use whenever a
+  task will end, or might end, in a pull request or issue on someone else's
+  repository: fixing a bug found upstream, contributing a patch, filing a
+  finding, answering a maintainer's review, or cleaning up after a merge or a
+  close. Also use when the user says "housebroken", "file this upstream",
+  "open a PR on", "send this to the maintainers", or asks whether a patch is
+  ready to file. Do NOT use for pull requests inside the user's own
+  repositories.
+license: MIT
+---
+
+# housebroken
+
+You are about to knock on a maintainer's door. She runs the project on
+evenings and weekends and closes most agent pull requests without reading
+them, because most of them deserve it. Every rule below was paid for with a
+closed pull request. You do not skip a rule because the patch is small.
+
+## Persistence
+
+Active from the moment a task might produce a pull request or an issue on a
+repository the user does not own, until the pull request is merged or closed
+and the fork branch is deleted. Still active if unsure. Off only when the user
+says "not upstream" or the repository is the user's own.
+
+## The door, in order
+
+Stop at the first step that fails. A failed step is a result, not an obstacle:
+report it in one line and do not proceed to the next step.
+
+1. **Read the house rules before knocking.**
+   `housebroken policy owner/repo` reads the contribution policy on the
+   default branch and in the organization's `.github` repository and prints
+   the sentence. Read it, then read it on the development branch too
+   (`--branch dev`) when one exists. If the policy asks contributors not to
+   use AI for pull request or issue text, stop: never file there with text
+   you wrote. If the project accepts pull requests only for labelled issues,
+   the deliverable is an issue with the fix offered, not a pull request.
+   `housebroken outside owner/repo` counts outside contributors merged in the
+   last 120 days. Zero means the project is closed to outsiders whatever its
+   README says; stop.
+
+2. **Is it already on the table?**
+   `housebroken prior-art owner/repo <file or symbol> ... --out` lists every
+   issue and pull request, open, closed and merged, that touches what the
+   patch touches, with the type stated and the closing ruling quoted for
+   every closed item. Read every closed item. An open pull request that fixes
+   the same thing means you stop and say so. A closed issue that ruled the
+   behavior intended means you stop and say so; you never argue with a
+   ruling. The printout is required by step 9; write it before the branch
+   exists.
+
+3. **Is it a fix or an opinion?**
+   A change that rejects an input the project tolerated, or changes a
+   default, is a breaking change on a stable major, however wrong the old
+   behavior looks. It becomes an issue that describes the behavior and offers
+   the patch, never a pull request. Classify every patch before writing a
+   test for it.
+
+4. **Prove it red first.**
+   On a fresh clone of the upstream default branch, not the tree you found
+   the bug in, write the test that fails. Run it and keep the failing output.
+   Apply the patch. Run it again. Both results go into the pull request as
+   the test itself; the body states the fact in one sentence.
+
+5. **Run their CI, not yours.**
+   Run the project's own test target on the fresh clone, and every gate its
+   pull request workflow runs: lint, format, mutation, API check. Read the
+   workflow file to find them. A gate you did not run is a red check the
+   maintainer sees before you do. When the repository ships a Dangerfile, a
+   pre-commit config or a commitlint config, those are its acceptance
+   criteria in machine-readable form; run them.
+
+6. **Match the house style.**
+   One finding, one pull request, the smallest diff that fixes it. No
+   comment in code that has none: run `housebroken census <clone root>` and
+   compare the added-comment ratio with the file. The body is under 120 words,
+   in the project's template if it has one, and says what was wrong, what the
+   change does, and how it was verified. No tool footer, no session link, no
+   co-author trailer, no typographic dashes. When a template asks whether AI
+   was used, answer in one truthful sentence.
+
+7. **Know the paperwork.**
+   Before the first pull request to an organization, find its agreement: CLA,
+   DCO sign-off, signed-commit requirement, disclosure trailer. Some CLA
+   actions post nothing on the pull request and write the instructions into a
+   failed job's log; read the log when a check named cla or license is red.
+   Some organizations want a trailer such as Assisted-by or Generated-by and
+   some forbid one; use exactly what the organization asks.
+
+8. **Security goes through the side door.**
+   A memory-safety, remote-abort, injection or path-escape finding in a
+   library goes by the project's SECURITY.md route, privately, with the
+   reproduction and the patch attached. It never becomes a public issue or
+   pull request until the project answers.
+
+9. **File through the gate.**
+   `housebroken file owner/repo --title ... --body-file ...` is the only way a
+   pull request is opened. Never run the pull request creation command
+   directly. The gate refuses when the prior-art printout for that repository
+   is missing or older than a day, or when the body carries a footer, a
+   trailer or a dash character. A refusal is a result; fix the cause.
+
+10. **Watch it land.**
+    `housebroken verify owner/repo PR` re-derives from GitHub that the head is
+    the intended commit, the diff is exactly the intended files, and CI
+    settled. `housebroken sweep` lists every open pull request where the ball
+    is in your court. Answer every maintainer comment the same day, in the
+    user's voice, after reading the whole thread. Rework what is asked for as
+    a second commit so the reviewer sees the change. When the maintainer is
+    right, concede in one sentence and let them close it. Never nudge a
+    silent maintainer without the user's explicit word.
+
+11. **Clean up.**
+    `housebroken hygiene` deletes the fork branch of every merged or closed
+    pull request and lists forks with no pull request left; delete those when
+    the work is over. No planning file, agent directory, journal or build
+    output ever enters a diff.
+
+12. **Three per repository, one finding each.**
+    Never more than three open pull requests on one repository. Each one
+    finding, each passing every step above on its own. GitHub lets
+    maintainers cap open pull requests from non-collaborators and counts
+    agent-opened ones against that cap.
+
+## What you say to the user
+
+Before filing: the repository, the finding in one sentence, the prior-art
+result in one sentence, the red-then-green result, the agreement the
+organization wants, and the exact command you are about to run. After
+filing: the pull request URL and the verify result. On a refusal at any
+step: which step, and the one sentence that explains it.
+
+## Never
+
+Never open a pull request without the prior-art printout. Never argue with a
+ruling in a closed issue. Never file where the policy asks you not to. Never
+put a footer, a session link or a co-author trailer on anything that leaves
+the user's repositories. Never post a comment upstream that the user has not
+seen. Never claim a test ran that you did not run.

housebroken_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: housebroken-cli
+Version: 0.1.0
+Summary: Agent-written pull requests that do not make a mess in someone else's house.
+Project-URL: Repository, https://github.com/lenamonj/housebroken
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/door.jpg" width="560" alt="A white ceramic robot dog sits at an open, lit door, a scroll in its mouth, its paws stopped at a glowing amber line on the threshold">
+</p>
+
+<h1 align="center">housebroken</h1>
+
+<p align="center"><em>Agent-written pull requests that do not make a mess in someone else's house.</em></p>
+
+<p align="center">
+  <img src="https://img.shields.io/github/stars/lenamonj/housebroken?style=flat-square&color=111111&label=stars" alt="Stars">
+  <img src="https://img.shields.io/github/v/release/lenamonj/housebroken?style=flat-square&color=111111&label=release" alt="Release">
+  <img src="https://img.shields.io/pypi/v/housebroken-cli?style=flat-square&color=111111&label=pypi" alt="PyPI">
+  <img src="https://img.shields.io/badge/works%20with-Claude%20Code-111111?style=flat-square" alt="Works with Claude Code">
+  <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT license">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/gates-12-E8A23B?style=flat-square" alt="12 gates">
+  <img src="https://img.shields.io/badge/merged%20upstream-24%20PRs%20in%2021%20projects-E8A23B?style=flat-square" alt="24 merged pull requests across 21 projects">
+  <img src="https://img.shields.io/badge/closures%20turned%20into%20gates-5-E8A23B?style=flat-square" alt="5 closures turned into gates">
+  <img src="https://img.shields.io/badge/shellcheck-clean-111111?style=flat-square" alt="shellcheck clean">
+</p>
+
+<p align="center">
+  <strong>24 merged upstream &middot; 21 projects &middot; 5 closures, each one now a gate</strong><br>
+  <sub>Derived from GitHub on 7 September 2026: one account, every patch written by an agent, every filing governed by these rules as they were learned. Apple, Microsoft, Google, Apache and JetBrains are among the mergers. <a href="#numbers">The numbers</a> &middot; <a href="#how-it-works">the twelve gates</a>.</sub>
+</p>
+
+You know the maintainer. She runs the project on evenings and weekends, has for nine years, and opened GitHub this morning to four pull requests from accounts created last month. Each one rewrites a function she wrote in 2019. Each carries a paragraph of comments in code that had none, a six-hundred-word body, and a footer naming the tool that wrote it. One of them re-argues a decision she closed in April. She closes all four without reading them.
+
+She is right to.
+
+housebroken is the set of rules that get a pull request past her, written as scripts that refuse to file until every rule is met. The rules are not opinions. Each one was paid for with a closed pull request, and the closure is named next to the rule.
+
+## Before / after
+
+Before: one branch, fourteen files, three unrelated fixes, a planning document and an agent config directory in the diff, a comment on every added line, a body that explains the tool, filed against a ruling already made in a closed issue, the project's own test target never run.
+
+After:
+
+```
+one finding, one pull request
+9 lines changed in the project's own style, no comment where the file has none
+1 test that fails on their main and passes with the patch
+body under 120 words, in their template, no footer
+prior art read and quoted before the branch existed
+their CI target green on a fresh clone of their main
+the CLA known before filing, the SECURITY.md route taken when it applies
+```
+
+The second one gets merged. Sometimes in twelve minutes.
+
+## Numbers
+
+Every rule here was learned on real repositories with real maintainers. Between late July and 7 September 2026, one account filed pull requests on projects it had never touched before, every patch written by an autonomous agent, every filing governed by these gates as they were learned. Derived from GitHub on 7 September 2026:
+
+| | count |
+|---|--:|
+| pull requests filed | 102 |
+| merged | 24, across 21 projects |
+| open, waiting on a maintainer | 73 |
+| closed without merging | 5 |
+
+The merged patches include ones accepted by Apple, Microsoft, Google, Apache, JetBrains, and the URL parser that Node.js ships. The fastest merge came twelve minutes after filing. Several came the same day.
+
+The five closures matter more than the merges. Each became a gate. Two of the five were the same class, three days apart, because the first lesson was written as prose and prose is followed when remembered. That is why the rules here are scripts that refuse, not a checklist that suggests.
+
+## How it works
+
+<img align="right" width="230" src="assets/treatise.jpg" alt="An obsidian book with chrome corners titled The Housebroken Agent, a treatise on manners for machines calling at the homes of maintainers">
+
+A pull request passes through the door in order. Each step is a script or a rule, and each names the closure that put it there.
+
+**1. Read the house rules before knocking.**
+`check-ai-policy.sh` reads the repository's contribution policy on its development branch and in the organization's `.github` repository, and prints the sentence, not a verdict. Some projects ask contributors not to use AI for pull request text; those are never filed. Some accept pull requests only for issues they have labelled; those get an issue with the fix offered.
+`distinct-outside.sh` counts outside contributors merged in the last 120 days. A project that has merged none is closed to outsiders whatever its README says.
+
+**2. Is it already on the table?**
+`prior-art.sh` lists every issue and pull request, open, closed and merged, that touches the file or symbol, with the type taken from the API field and the closing ruling quoted for every closed item. Two closures built it: a pull request that duplicated an open pull request because a search mixed issues and pull requests and nobody checked the type, and a pull request that argued against a ruling in a closed issue nobody had read.
+
+**3. Is it a fix or an opinion?**
+A change that rejects an input the project tolerated, or changes a default, is a breaking change on a stable major. It becomes an issue, never a pull request. Two closures, one class, two projects, before this was a rule.
+
+**4. Prove it red first.**
+On a fresh clone of the upstream default branch, the new test fails. With the patch, it passes. The proof lives in the pull request as the test, not in the body as a claim.
+
+**5. Run their CI, not yours.**
+The project's own test target, on the fresh clone, including the lint, format and mutation gates its workflow runs. Two pull requests went red on gates the author had never run, and the maintainer saw it before the author did.
+
+**6. Match the house style.**
+`comment-census.sh` counts added code lines against added comment lines and compares them with the file. No comment in code that has none. Body under 120 words, in the project's template if it has one. No tool footer, no session link, no co-author trailer. When a template asks whether AI was used, the answer is one truthful sentence. Three maintainers said the same thing about comment density before it became a script.
+
+**7. Know the paperwork.**
+Every organization gets a card before the first filing: CLA, DCO, signed-commit requirement, template. Some CLA bots post nothing on the pull request and put the instructions in a failed job's log; the card is where that is written down.
+
+**8. Security goes through the side door.**
+A memory-safety or remote-abort finding in a library goes by the project's SECURITY.md route, privately, and never becomes a public pull request until the project answers.
+
+**9. File through the gate.**
+`file-pr.sh` wraps the pull request creation and refuses when the prior-art printout for that repository is missing or older than a day, or when the body carries a footer, a trailer, or a typographic dash.
+
+**10. Watch it land.**
+`verify-filed-pr.sh` re-derives from GitHub that the head is the intended commit, the diff is exactly the intended files, and CI settled green. `pr-sweep.sh` lists every open pull request where the ball is in your court: a maintainer's comment unanswered, a review requesting changes, a red check, a conflict. Every maintainer comment gets a same-day answer. A ruling in a closed issue is never argued with. When the maintainer is right, concede and let them close it.
+
+**11. Clean up.**
+`fork-hygiene.sh` deletes the fork branch of every merged or closed pull request and lists forks with no pull request left, which are deleted when the work is over. No planning file, agent directory or build output ever enters a diff.
+
+**12. Three per repository, one finding each.**
+A repository gets at most three pull requests, each one finding, each meeting every rule above on its own.
+
+## Install
+
+You need `bash`, `gh` (signed in) and `jq`. Then:
+
+```
+uv tool install housebroken-cli
+housebroken install-skill
+```
+
+The first line puts the `housebroken` command on your path. The second puts the skill where Claude Code loads it, so the agent runs the door itself before it opens anything upstream. Until the package is on PyPI, install from the repository instead:
+
+```
+uv tool install git+https://github.com/lenamonj/housebroken
+```
+
+`housebroken help` prints the door in order. Every gate is also a plain bash script under `scripts/`, runnable on its own.
+
+## What is in the repository
+
+| script | gate |
+|---|---|
+| `scripts/check-ai-policy.sh` | reads the AI-contribution policy where it actually lives |
+| `scripts/distinct-outside.sh` | outside contributors merged in 120 days |
+| `scripts/prior-art.sh` | issues and pull requests on the touched files, type stated, rulings quoted |
+| `scripts/comment-census.sh` | added code versus added comments, per branch |
+| `scripts/file-pr.sh` | the only way a pull request gets filed |
+| `scripts/verify-filed-pr.sh` | the filed pull request is what was meant, and CI settled |
+| `scripts/pr-sweep.sh` | every open pull request where the ball is in your court |
+| `scripts/fork-hygiene.sh` | branches deleted after merge or close, orphan forks listed |
+
+The scripts are bash and need `gh` and `jq`. They came out of one operator's workshop and some still carry that operator's assumptions; each script's header says what it assumes. Generalizing them is the current work.
+
+## Not in scope
+
+housebroken does not find bugs and does not write patches. Any agent that produces a change can use it. It governs what leaves your machine and how it behaves once it arrives.
+
+## FAQ
+
+**Is this only for AI-written pull requests?**
+No. Every rule here predates agents. Agents made it cheap to break all of them at once, on a hundred repositories, before breakfast.
+
+**Does it make maintainers like agent pull requests?**
+No. It makes the pull request indistinguishable from a careful human's, and answers truthfully when they ask.
+
+**What if the maintainer closes it anyway?**
+Then the maintainer is the judge and the ruling stands. Read why, write it down, and if it is a class of mistake, make it a gate.
+
+**Why "housebroken"?**
+Because the alternative is what maintainers are calling it.
+
+## License
+
+MIT.

housebroken_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+housebroken/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+housebroken/cli.py,sha256=ADd1Q07beO7H1MPurm4J8R1_AIQKsz9DYpCV152wKlo,2668
+housebroken/scripts/check-ai-policy.sh,sha256=bwFVs1xCb7o6inWUQu6mu-tkNUGm_-5V-gfCmoBVKoA,4157
+housebroken/scripts/comment-census.sh,sha256=9LvRfoFe4upc7BGyX3izgbKmTgOMR4_Fplx-ESfd2-Q,3208
+housebroken/scripts/distinct-outside.sh,sha256=eJ6hjFUjkDAHBikUh5-4XAO8PIjJKKc-goSGCJ_QUe0,3580
+housebroken/scripts/file-pr.sh,sha256=V6FtonHEiq7_jmnSC6BDl7WBhXcmgjod5kNuJzLxxF4,3968
+housebroken/scripts/fork-hygiene.sh,sha256=0YJ-7Usbz0_kpbA25ZAm7U5OgtkJgjnRBv72IB6RnkA,3199
+housebroken/scripts/pr-sweep.sh,sha256=wzN1sLkbTcqN2ksJtDoiyjcCEYPJbVSy41eLSU3P8VQ,3572
+housebroken/scripts/prior-art.sh,sha256=tWNYKdN8-SA_WJcY-bk-HhI1GV_jMfA0ab4bui2uHFU,5989
+housebroken/scripts/verify-filed-pr.sh,sha256=arXeZbdAavcbHBjUTZFDeOpPdQT2TaXN6b-RNxvZrxo,2944
+housebroken/scripts/housebroken,sha256=uS8U_MjOtBFxU_iM5eclFnxJJTa0OlPQd0zL8iO1wpI,3576
+housebroken/skill/SKILL.md,sha256=ITHQL-h46QQzs-xSlhBUCJVHb-vcIoyKP7wXL-d2j34,7512
+housebroken_cli-0.1.0.dist-info/METADATA,sha256=9yNJVI_kUV36YtWzH0pb9erhbFOIaG-gPVew7NDZTg0,11414
+housebroken_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+housebroken_cli-0.1.0.dist-info/entry_points.txt,sha256=hdjaU5C4ymyzypEnIGFEEeZCxV5J0IcgW5Hf0q6vvXk,53
+housebroken_cli-0.1.0.dist-info/licenses/LICENSE,sha256=fPHbuTJO3PJp8BlBoRP3es2egezKw2uOpYmbcHa4Rwo,1110
+housebroken_cli-0.1.0.dist-info/RECORD,,

housebroken_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

housebroken_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+housebroken = housebroken.cli:main