housebroken-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{housebroken_cli-0.1.0 → housebroken_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: housebroken-cli
-Version: 0.1.0
+Version: 0.2.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
@@ -11,7 +11,7 @@ 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">
+  <img src="https://raw.githubusercontent.com/lenamonj/housebroken/main/assets/door.jpg" width="560" alt="A white ceramic robot dog sits at an open, lit door, a scroll in its mouth, its paws stopped at a glowing amber line on the threshold">
 </p>
 
 <h1 align="center">housebroken</h1>
@@ -28,13 +28,13 @@ Description-Content-Type: text/markdown
 
 <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/merged%20upstream-29%20PRs%20in%2023%20projects-E8A23B?style=flat-square" alt="29 merged pull requests across 23 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>
+  <strong>29 merged upstream &middot; 23 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>
 
@@ -68,9 +68,9 @@ Every rule here was learned on real repositories with real maintainers. Between
 
 | | count |
 |---|--:|
-| pull requests filed | 102 |
-| merged | 24, across 21 projects |
-| open, waiting on a maintainer | 73 |
+| pull requests filed | 115 |
+| merged | 29, across 23 projects |
+| open, waiting on a maintainer | 81 |
 | 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.
@@ -79,9 +79,9 @@ The five closures matter more than the merges. Each became a gate. Two of the fi
 
 ## 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">
+<img align="right" width="230" src="https://raw.githubusercontent.com/lenamonj/housebroken/main/assets/treatise.jpg" alt="An obsidian book with chrome corners titled The Housebroken Agent, a treatise on manners for machines calling at the homes of maintainers">
 
-A pull request passes through the door in order. Each step is a script or a rule, and each names the closure that put it there.
+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. The verdicts themselves, in the maintainers' words, are in [docs/lessons.md](https://github.com/lenamonj/housebroken/blob/main/docs/lessons.md).
 
 **1. Read the house rules before knocking.**
 `check-ai-policy.sh` reads 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.
@@ -122,10 +122,10 @@ A repository gets at most three pull requests, each one finding, each meeting ev
 
 ## Install
 
-You need `bash`, `gh` (signed in) and `jq`. Then:
+You need `bash`, `gh` (signed in) and `jq`. Then, from PyPI; `pipx install housebroken-cli` and `uv tool install housebroken-cli` work the same way:
 
 ```
-uv tool install housebroken-cli
+pip install housebroken-cli
 housebroken install-skill
 ```
 
@@ -145,9 +145,11 @@ uv tool install git+https://github.com/lenamonj/housebroken
 | `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/diff-defaults.sh` | default arguments and one-line wrappers added to keep call sites untouched |
 | `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/notes.sh` | what this repository's maintainers have asked for before |
 | `scripts/fork-hygiene.sh` | branches deleted after merge or close, orphan forks listed |
 
 The scripts are bash and need `gh` and `jq`. 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.

{housebroken_cli-0.1.0 → housebroken_cli-0.2.0}/README.md

@@ -16,13 +16,13 @@
 
 <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/merged%20upstream-29%20PRs%20in%2023%20projects-E8A23B?style=flat-square" alt="29 merged pull requests across 23 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>
+  <strong>29 merged upstream &middot; 23 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>
 
@@ -56,9 +56,9 @@ Every rule here was learned on real repositories with real maintainers. Between
 
 | | count |
 |---|--:|
-| pull requests filed | 102 |
-| merged | 24, across 21 projects |
-| open, waiting on a maintainer | 73 |
+| pull requests filed | 115 |
+| merged | 29, across 23 projects |
+| open, waiting on a maintainer | 81 |
 | 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.
@@ -69,7 +69,7 @@ The five closures matter more than the merges. Each became a gate. Two of the fi
 
 <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.
+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. The verdicts themselves, in the maintainers' words, are in [docs/lessons.md](docs/lessons.md).
 
 **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.
@@ -110,10 +110,10 @@ A repository gets at most three pull requests, each one finding, each meeting ev
 
 ## Install
 
-You need `bash`, `gh` (signed in) and `jq`. Then:
+You need `bash`, `gh` (signed in) and `jq`. Then, from PyPI; `pipx install housebroken-cli` and `uv tool install housebroken-cli` work the same way:
 
 ```
-uv tool install housebroken-cli
+pip install housebroken-cli
 housebroken install-skill
 ```
 
@@ -133,9 +133,11 @@ uv tool install git+https://github.com/lenamonj/housebroken
 | `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/diff-defaults.sh` | default arguments and one-line wrappers added to keep call sites untouched |
 | `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/notes.sh` | what this repository's maintainers have asked for before |
 | `scripts/fork-hygiene.sh` | branches deleted after merge or close, orphan forks listed |
 
 The scripts are bash and need `gh` and `jq`. 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.

{housebroken_cli-0.1.0 → housebroken_cli-0.2.0}/bin/housebroken

@@ -1,5 +1,5 @@
 #!/bin/bash
-# housebroken - one command name for the eight gate scripts.
+# housebroken - one command name for the nine gate scripts.
 #
 # The skill file, and any future adapter for another agent host, must be able
 # to say `housebroken prior-art owner/repo term` without knowing where the
@@ -13,7 +13,7 @@
 #   housebroken version
 #
 # Environment:
-#   HOUSEBROKEN_SCRIPTS  directory holding the eight *.sh gate scripts. When
+#   HOUSEBROKEN_SCRIPTS  directory holding the nine *.sh gate scripts. When
 #                        unset, the scripts directory next to this file
 #                        (../scripts), then this file's own directory, then
 #                        $HOUSEBROKEN_HOME/scripts are tried in that order.
@@ -51,6 +51,7 @@ usage: housebroken <subcommand> [args...]
   9  file        the only way a pull request gets filed
  10  verify      the filed pull request is what was meant, and CI settled
  10  sweep       every open pull request where the ball is in your court
+ 10  notes       what this repository's maintainers have asked for before
  11  hygiene     delete fork branches after merge or close, list orphan forks
 
   help           this list
@@ -90,6 +91,7 @@ case "$cmd" in
   file)      script=file-pr.sh ;;
   verify)    script=verify-filed-pr.sh ;;
   sweep)     script=pr-sweep.sh ;;
+  notes)     script=notes.sh ;;
   hygiene)   script=fork-hygiene.sh ;;
   *)
     echo "housebroken: unknown subcommand: $cmd (try: housebroken help)" >&2

housebroken_cli-0.2.0/hatch_build.py

@@ -0,0 +1,24 @@
+"""Rewrite the README for PyPI at build time.
+
+PyPI renders the project description from README.md but cannot resolve
+relative paths, so images under assets/ and links to files in the repository
+render broken there. This hook turns every relative src, srcset and markdown
+link into an absolute GitHub URL in the built metadata only; the README in the
+repository stays relative, which is what GitHub wants.
+"""
+import os
+import re
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+
+
+class ReadmeHook(MetadataHookInterface):
+    def update(self, metadata):
+        repo = self.config["repo"]
+        raw = f"https://raw.githubusercontent.com/{repo}/main/"
+        blob = f"https://github.com/{repo}/blob/main/"
+        with open(os.path.join(self.root, "README.md"), encoding="utf-8") as f:
+            text = f.read()
+        text = re.sub(r'((?:src|srcset)=")(?!https?://)([^"]+)"', lambda m: f'{m.group(1)}{raw}{m.group(2)}"', text)
+        text = re.sub(r'\]\((?!https?://|#|mailto:)([^)\s]+)\)', lambda m: f"]({blob}{m.group(1)})", text)
+        metadata["readme"] = {"content-type": "text/markdown", "text": text}

{housebroken_cli-0.1.0 → housebroken_cli-0.2.0}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "hatchling.build"
 
 [project]
 name = "housebroken-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Agent-written pull requests that do not make a mess in someone else's house."
-readme = "README.md"
+dynamic = ["readme"]
 license = "MIT"
 requires-python = ">=3.10"
 dependencies = []
@@ -38,3 +38,7 @@ include = [
   "README.md",
   "LICENSE",
 ]
+
+[tool.hatch.metadata.hooks.custom]
+path = "hatch_build.py"
+repo = "lenamonj/housebroken"

housebroken_cli-0.2.0/scripts/comment-census.sh

@@ -0,0 +1,171 @@
+#!/bin/bash
+# comment-census.sh - added code lines against added comment lines, per branch,
+# plus a neighbourhood check on every added comment.
+#
+# A patch that carries a paragraph of comments into a file that has none reads
+# as machine-written and gets closed. This counts, for every branch in every
+# clone under a directory, the added non-comment lines and the added comment
+# lines, so a pull request can be made to match the comment density of the file
+# it lands in. Three maintainers asked for exactly this, in three separate
+# reviews, before it became a script.
+#
+# A fourth asked for more. On google/benchmark #2294 the maintainer called a
+# single comment above a two-line fix "unnecessary comment" in a file whose
+# overall ratio was healthy: he judged the comment against the function around
+# it, not against the file. So every added comment line is also checked against
+# its neighbourhood - the 20 lines above and the 20 lines below it on the
+# branch, excluding the added lines themselves. If none of those lines is a
+# comment, the added comment is flagged whatever the file ratio says. A shebang
+# or a licence header in the first 15 lines does not rescue a comment added
+# further down.
+#
+# Usage:
+#   bash comment-census.sh [CLONE_ROOT]
+#   bash comment-census.sh --help
+#
+# CLONE_ROOT is any directory whose immediate subdirectories are git clones.
+# Defaults to $HOUSEBROKEN_CLONES, then to $HOUSEBROKEN_HOME/clones.
+#
+# Environment:
+#   HOUSEBROKEN_CLONES  default clone root
+#   HOUSEBROKEN_HOME    workshop root, default $HOME/.housebroken
+#
+# Assumes: each clone has an origin remote whose default branch is discoverable
+# (origin/HEAD, else origin/main, else origin/master); every other local branch
+# is a candidate patch. Tests, markdown and lock files are excluded from the
+# code and comment counts. Comment detection covers //, /* */, * and #.
+# Neighbourhood detection picks the comment family from the file extension:
+# //, /* */ for .c .cc .cpp .h .hpp .go .rs .java .kt .swift .ts .js, # for
+# .py .rb .sh .toml .yaml .yml, and ; for .asm .s .lisp .el .clj. A file with
+# any other extension gets no neighbourhood check.
+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
+
+HOUSEBROKEN_HOME="${HOUSEBROKEN_HOME:-$HOME/.housebroken}"
+root="${1:-${HOUSEBROKEN_CLONES:-$HOUSEBROKEN_HOME/clones}}"
+
+if [ ! -d "$root" ]; then
+  echo "comment-census.sh: not a directory: $root" >&2
+  echo "give a clone root as an argument or set HOUSEBROKEN_CLONES" >&2
+  exit 1
+fi
+
+paths=(. ':(exclude)*test*' ':(exclude)*Test*' ':(exclude)*_test.go' ':(exclude)Tests/*' ':(exclude)*.md' ':(exclude)*.sum')
+
+# Comment family for an extension, as an ERE. Returns 1 for unknown extensions.
+comment_re() {
+  case "$1" in
+    c|cc|cpp|h|hpp|go|rs|java|kt|swift|ts|js) printf '%s' '^[[:space:]]*(//|/[*]|[*]|[*]/)' ;;
+    py|rb|sh|toml|yaml|yml) printf '%s' '^[[:space:]]*#' ;;
+    asm|s|lisp|el|clj) printf '%s' '^[[:space:]]*;' ;;
+    *) return 1 ;;
+  esac
+}
+
+flagfile=$(mktemp) || exit 1
+trap 'rm -f "$flagfile"' EXIT
+
+flag_scan() {
+  local d="$1" base="$2" br="$3" name="$4"
+  local map content addedset cur row f ln text e re lo hi body
+  local rows=()
+  map=$(mktemp) || return 1
+  content=$(mktemp) || { rm -f "$map"; return 1; }
+  addedset=$(mktemp) || { rm -f "$map" "$content"; return 1; }
+
+  git -C "$d" diff --unified=0 "$base..$br" -- "${paths[@]}" | awk '
+    /^\+\+\+ / { file=""; if (substr($0,1,6) == "+++ b/") file=substr($0,7); next }
+    /^--- /    { next }
+    /^@@ /     { split($3, a, ","); ln=substr(a[1],2)+0; next }
+    /^\+/      { if (file != "") { print file "\t" ln "\t" substr($0,2); ln++ } next }
+    /^ /       { ln++ }
+  ' > "$map"
+
+  mapfile -t rows < "$map"
+  cur=""
+  for row in ${rows[@]+"${rows[@]}"}; do
+    IFS=$'\t' read -r f ln text <<< "$row"
+    e="${f##*.}"
+    re=$(comment_re "$e") || continue
+    printf '%s\n' "$text" | grep -qE "$re" || continue
+    if [ "$f" != "$cur" ]; then
+      cur="$f"
+      git -C "$d" show "$br:$f" > "$content" 2>/dev/null || : > "$content"
+      awk -F'\t' -v want="$f" '$1 == want { print $2 }' "$map" > "$addedset"
+    fi
+    lo=$((ln - 20))
+    [ "$lo" -lt 1 ] && lo=1
+    hi=$((ln + 20))
+    body=0
+    [ "$ln" -gt 15 ] && body=1
+    if ! awk -v lo="$lo" -v hi="$hi" -v body="$body" -v self="$ln" -v re="$re" -v af="$addedset" '
+      BEGIN { found=0; while ((getline a < af) > 0) added[a+0]=1 }
+      NR < lo { next }
+      NR > hi { exit }
+      NR == self { next }
+      added[NR] { next }
+      body == 1 && NR <= 15 { next }
+      $0 ~ re { found=1; exit }
+      END { exit (found ? 0 : 1) }
+    ' "$content"; then
+      printf 'FLAG %s %s %s:%s %s\n' "$name" "$br" "$f" "$ln" "$text" >> "$flagfile"
+    fi
+  done
+
+  rm -f "$map" "$content" "$addedset"
+}
+
+printf '%-28s %-36s %5s %5s %5s\n' repo branch code cmnt tests
+
+found=0
+for d in "$root"/*/; do
+  [ -d "$d/.git" ] || continue
+  found=1
+  name=$(basename "$d")
+  base=$(git -C "$d" symbolic-ref -q --short refs/remotes/origin/HEAD || true)
+  if [ -z "$base" ]; then
+    if git -C "$d" rev-parse --verify -q origin/main >/dev/null; then
+      base=origin/main
+    elif git -C "$d" rev-parse --verify -q origin/master >/dev/null; then
+      base=origin/master
+    else
+      echo "comment-census.sh: no default branch in $d, skipped" >&2
+      continue
+    fi
+  fi
+  default_branch="${base#origin/}"
+  while read -r br; do
+    [ -n "$br" ] || continue
+    [ "$br" = "$default_branch" ] && continue
+    [ "$(git -C "$d" rev-list --count "$base..$br")" = "0" ] && continue
+    added=$(git -C "$d" diff "$base..$br" -- "${paths[@]}" | grep '^+' | grep -v '^+++' || true)
+    if [ -z "$added" ]; then
+      code=0; cmnt=0
+    else
+      code=$(printf '%s\n' "$added" | grep -v -E '^\+\s*(//|/\*|\*|#|///|\*/)' | grep -c -v -E '^\+\s*$' || true)
+      cmnt=$(printf '%s\n' "$added" | grep -c -E '^\+\s*(//|/\*|\*|///|\*/)' || true)
+    fi
+    tests=$(git -C "$d" diff "$base..$br" --numstat | awk '/[Tt]est/{s+=$1} END{print s+0}')
+    printf '%-28s %-36s %5s %5s %5s\n' "$name" "$br" "$code" "$cmnt" "$tests"
+    flag_scan "$d" "$base" "$br" "$name"
+  done < <(git -C "$d" for-each-ref --format='%(refname:short)' refs/heads/)
+done
+
+if [ "$found" = 0 ]; then
+  echo "comment-census.sh: no git clones found under $root" >&2
+  exit 1
+fi
+
+if [ -s "$flagfile" ]; then
+  echo
+  cat "$flagfile"
+fi
+echo
+echo "$(grep -c '^FLAG ' "$flagfile" || true) comment lines added into comment-free neighbourhoods"

housebroken_cli-0.2.0/scripts/diff-defaults.sh

@@ -0,0 +1,222 @@
+#!/bin/bash
+# diff-defaults.sh - added default arguments and one-line forwarding wrappers.
+#
+# On google/benchmark #2294 the maintainer asked "why are there defaults here?"
+# about two default arguments added so that ten existing call sites did not
+# have to change. A default argument, an overload or a one-line wrapper that
+# exists only to keep call sites untouched hides the change from the reader and
+# leaves the old behaviour reachable. The fix is to touch the call sites. This
+# script reads the added lines of a diff and reports both shapes so the author
+# sees them before the maintainer does. It reports, it does not judge: the exit
+# status is 0 whether or not anything was found.
+#
+# Usage:
+#   bash diff-defaults.sh [CLONE_ROOT]
+#   bash diff-defaults.sh --diff FILE
+#   bash diff-defaults.sh --diff -
+#   bash diff-defaults.sh --help
+#
+# CLONE_ROOT is any directory whose immediate subdirectories are git clones;
+# every branch is diffed against its clone's default branch. With --diff, a
+# unified diff is read from FILE, or from standard input when FILE is -.
+#
+# Environment:
+#   HOUSEBROKEN_CLONES  default clone root
+#   HOUSEBROKEN_HOME    workshop root, default $HOME/.housebroken
+#
+# Output is one line per hit, "file:line  kind  text", where kind is
+# default-arg or forwarding, followed by a summary count.
+#
+# Languages: C, C++, Python, Kotlin, Swift, TypeScript and JavaScript, by
+# extension (.c .cc .cpp .h .hpp .py .kt .swift .ts .js). Other files are
+# ignored.
+#
+# Heuristic. Working one added line at a time, with no parser and no view of
+# the surrounding function, the script calls a line a signature when it holds
+# an assignment whose left side ends in an identifier and one of these is true:
+#   - the assignment sits between the line's first ( and its last ), and
+#     nothing after that ) opens another paren:  void Run(int n, bool v = 0);
+#   - the line opens a parameter list it does not close, and the assignment is
+#     after the (
+#   - the line closes a parameter list it did not open, and the assignment is
+#     before the )
+#   - the trimmed line ends with a comma, the shape of a parameter continuation
+# A forwarding wrapper is an added line that defines a name and calls that same
+# name again on the same line, with a return, an =>, an = or a { between them.
+#
+# Known misses. False positives: a keyword or designated argument written with
+# = inside a call, "foo(a, b = 5);"; a brace-initialiser or array element
+# ending in a comma, though a leading . is skipped; a recursive one-line
+# function, which on one line looks exactly like a forwarding wrapper. False
+# negatives: a default on a signature split so that neither the identifier nor
+# the = lands on an added line; a forwarding wrapper whose body is on the next
+# line; a default introduced by a line the diff records as unchanged context;
+# C++ default template arguments and Python keyword-only markers are not
+# modelled.
+set -u
+
+usage() {
+  sed -n '2,/^set -u$/p' "$0" | sed 's/^# \{0,1\}//; /^set -u$/d'
+}
+
+mode="clones"
+diff_src=""
+case "${1:-}" in
+  --help|-h) usage; exit 0 ;;
+  --diff)
+    if [ $# -lt 2 ] || [ -z "$2" ]; then
+      echo "diff-defaults.sh: --diff needs a file or -" >&2
+      exit 2
+    fi
+    mode="diff"
+    diff_src="$2"
+    ;;
+  --*)
+    echo "diff-defaults.sh: unknown option: $1" >&2
+    exit 2
+    ;;
+esac
+
+analyzer=$(cat <<'AWK'
+function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t]+$/, "", s); return s }
+function ext(f,   n, a) { n = split(f, a, "."); return (n > 1) ? a[n] : "" }
+function supported(e) {
+  return (e=="c" || e=="cc" || e=="cpp" || e=="h" || e=="hpp" || e=="py" ||
+          e=="kt" || e=="swift" || e=="ts" || e=="js")
+}
+function countch(s, c,   i, n, k) { n=length(s); k=0; for (i=1;i<=n;i++) if (substr(s,i,1)==c) k++; return k }
+function lastidx(s, c,   i, n, k) { n=length(s); k=0; for (i=1;i<=n;i++) if (substr(s,i,1)==c) k=i; return k }
+# position of the first plain assignment =, skipping ==, !=, +=, and friends
+function eqpos(s,   i, n, p) {
+  n = length(s)
+  for (i = 1; i <= n; i++) {
+    if (substr(s,i,1) != "=") continue
+    if (substr(s,i+1,1) == "=") continue
+    p = (i > 1) ? substr(s,i-1,1) : ""
+    if (p ~ /[=!<>+*\/%&|^~-]/) continue
+    return i
+  }
+  return 0
+}
+function is_default(t,   s, eq, pre, oc, cc, fo, lc, tail) {
+  s = trim(t)
+  if (substr(s,1,1) == ".") return 0
+  eq = eqpos(s)
+  if (eq == 0) return 0
+  pre = trim(substr(s, 1, eq - 1))
+  if (pre !~ /[A-Za-z0-9_]$/) return 0
+  if (trim(substr(s, eq + 1)) == "") return 0
+  oc = countch(s, "("); cc = countch(s, ")")
+  fo = index(s, "("); lc = lastidx(s, ")")
+  if (fo > 0 && lc > fo && eq > fo && eq < lc) {
+    tail = substr(s, lc + 1)
+    if (index(tail, "(") == 0) return 1
+  }
+  if (oc > cc && fo > 0 && eq > fo) return 1
+  if (cc > oc && lc > 0 && eq < lc) return 1
+  if (substr(s, length(s), 1) == ",") return 1
+  return 0
+}
+function defname(s,   fo, j, e) {
+  fo = index(s, "(")
+  if (fo == 0) return ""
+  j = fo - 1
+  while (j > 0 && (substr(s,j,1) == " " || substr(s,j,1) == "\t")) j--
+  e = j
+  while (j > 0 && substr(s,j,1) ~ /[A-Za-z0-9_]/) j--
+  return substr(s, j + 1, e - j)
+}
+function ncalls(s, name,   i, n, L, p, j, k) {
+  n = length(s); L = length(name); k = 0
+  if (L == 0) return 0
+  for (i = 1; i <= n - L + 1; i++) {
+    if (substr(s,i,L) != name) continue
+    p = (i > 1) ? substr(s,i-1,1) : ""
+    if (p ~ /[A-Za-z0-9_]/) continue
+    j = i + L
+    while (substr(s,j,1) == " " || substr(s,j,1) == "\t") j++
+    if (substr(s,j,1) == "(") k++
+  }
+  return k
+}
+function is_forward(t,   s, name) {
+  s = trim(t)
+  name = defname(s)
+  if (name == "") return 0
+  if (name ~ /^(if|for|while|switch|return|catch|def|fun|func|function|new|sizeof)$/) return 0
+  if (ncalls(s, name) < 2) return 0
+  if (s ~ /return/ || index(s, "=>") > 0 || index(s, "=") > 0 || index(s, "{") > 0) return 1
+  return 0
+}
+/^\+\+\+ / { file = ""; if (substr($0,1,6) == "+++ b/") file = substr($0,7); next }
+/^--- /    { next }
+/^@@ /     { split($3, a, ","); ln = substr(a[1],2) + 0; next }
+/^\\/      { next }
+/^\+/ {
+  if (file != "") {
+    t = substr($0, 2)
+    if (supported(ext(file))) {
+      if (is_forward(t))      print file ":" ln "  forwarding  " t
+      else if (is_default(t)) print file ":" ln "  default-arg  " t
+    }
+    ln++
+  }
+  next
+}
+/^-/ { next }
+/^ / { ln++ }
+AWK
+)
+
+hits=$(mktemp) || exit 1
+trap 'rm -f "$hits"' EXIT
+
+if [ "$mode" = diff ]; then
+  if [ "$diff_src" = "-" ]; then
+    awk "$analyzer" >> "$hits"
+  else
+    if [ ! -f "$diff_src" ]; then
+      echo "diff-defaults.sh: not a file: $diff_src" >&2
+      exit 2
+    fi
+    awk "$analyzer" "$diff_src" >> "$hits"
+  fi
+else
+  HOUSEBROKEN_HOME="${HOUSEBROKEN_HOME:-$HOME/.housebroken}"
+  root="${1:-${HOUSEBROKEN_CLONES:-$HOUSEBROKEN_HOME/clones}}"
+  if [ ! -d "$root" ]; then
+    echo "diff-defaults.sh: not a directory: $root" >&2
+    echo "give a clone root as an argument or set HOUSEBROKEN_CLONES" >&2
+    exit 2
+  fi
+  found=0
+  for d in "$root"/*/; do
+    [ -d "$d/.git" ] || continue
+    found=1
+    base=$(git -C "$d" symbolic-ref -q --short refs/remotes/origin/HEAD || true)
+    if [ -z "$base" ]; then
+      if git -C "$d" rev-parse --verify -q origin/main >/dev/null; then
+        base=origin/main
+      elif git -C "$d" rev-parse --verify -q origin/master >/dev/null; then
+        base=origin/master
+      else
+        echo "diff-defaults.sh: no default branch in $d, skipped" >&2
+        continue
+      fi
+    fi
+    default_branch="${base#origin/}"
+    while read -r br; do
+      [ -n "$br" ] || continue
+      [ "$br" = "$default_branch" ] && continue
+      [ "$(git -C "$d" rev-list --count "$base..$br")" = "0" ] && continue
+      git -C "$d" diff --unified=0 "$base..$br" | awk "$analyzer" >> "$hits"
+    done < <(git -C "$d" for-each-ref --format='%(refname:short)' refs/heads/)
+  done
+  if [ "$found" = 0 ]; then
+    echo "diff-defaults.sh: no git clones found under $root" >&2
+    exit 2
+  fi
+fi
+
+cat "$hits"
+echo "$(grep -c . "$hits" || true) default arguments or forwarding wrappers added"

housebroken_cli-0.2.0/scripts/notes.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# notes.sh - what a repository's maintainers have asked for before.
+#
+# Preferences outlive one pull request. google/benchmark wants no comment and
+# no default arguments; Kotlin/kotlinx-datetime wants the test in the JVM suite
+# that compares against java.time; apple/swift-log wants the package's own Lock
+# in tests; cloudflare/circl answers its review bots itself. A note is written
+# once, when the maintainer says it, and read before the next pull request and
+# before every rework.
+#
+# Usage:
+#   bash notes.sh owner/repo                # print the notes for one repository
+#   bash notes.sh owner/repo add "<text>"   # append a dated line
+#   bash notes.sh --list                    # repositories that have notes
+#   bash notes.sh --help
+#
+# Environment:
+#   HOUSEBROKEN_HOME  workshop root, default $HOME/.housebroken. A repository's
+#                     notes live in $HOUSEBROKEN_HOME/notes/<owner>-<repo>.md
+#
+# Assumes: bash. No network, no gh, no jq.
+set -u
+
+usage() {
+  sed -n '2,/^set -u$/p' "$0" | sed 's/^# \{0,1\}//; /^set -u$/d'
+}
+
+NOTES_DIR="${HOUSEBROKEN_HOME:-$HOME/.housebroken}/notes"
+
+list_repos() {
+  found=0
+  for f in "$NOTES_DIR"/*.md; do
+    [ -f "$f" ] || continue
+    # the header line names the repository; the file name cannot, because an
+    # owner and a repository may both contain a hyphen
+    name="$(sed -n '1s/^# notes: //p' "$f")"
+    [ -n "$name" ] || name="$(basename "$f" .md)"
+    echo "$name"
+    found=1
+  done
+  [ "$found" = 1 ] || echo "no repositories have notes yet"
+}
+
+case "${1:-}" in
+  --help|-h) usage; exit 0 ;;
+  --list) list_repos; exit 0 ;;
+  "") echo "notes.sh: expected owner/repo, --list or --help" >&2; usage >&2; exit 2 ;;
+esac
+
+target="$1"
+case "$target" in
+  */*/*|/*|*/) echo "notes.sh: expected owner/repo, got: $target" >&2; exit 2 ;;
+  */*) ;;
+  *) echo "notes.sh: expected owner/repo, got: $target" >&2; exit 2 ;;
+esac
+file="$NOTES_DIR/${target%%/*}-${target#*/}.md"
+shift
+
+if [ $# -eq 0 ]; then
+  if [ -f "$file" ]; then
+    cat "$file"
+  else
+    echo "no notes for $target"
+  fi
+  exit 0
+fi
+
+[ "$1" = "add" ] || { echo "notes.sh: unknown action: $1" >&2; usage >&2; exit 2; }
+shift
+text="${1:-}"
+[ -n "$text" ] || { echo "notes.sh: add needs the note text" >&2; exit 2; }
+
+if ! mkdir -p "$NOTES_DIR"; then
+  echo "notes.sh: cannot create $NOTES_DIR" >&2
+  exit 1
+fi
+if [ ! -f "$file" ]; then
+  printf '# notes: %s\n' "$target" > "$file" || {
+    echo "notes.sh: cannot write $file" >&2; exit 1; }
+fi
+printf -- '- %s: %s\n' "$(date -u +%Y-%m-%d)" "$text" >> "$file" || {
+  echo "notes.sh: cannot append to $file" >&2; exit 1; }
+echo "noted for $target in $file"

{housebroken_cli-0.1.0 → housebroken_cli-0.2.0}/scripts/pr-sweep.sh

@@ -7,13 +7,21 @@
 # changes, CI has a failing check, or the PR is CONFLICTING (needs a rebase).
 # Read-only; acting is the operator's.
 #
+# A merge or a close drops a PR out of the open list without a word, so each
+# run writes its open set to a state file and the next run reports what left
+# it.
+#
 # 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                  # only PRs where the ball is in our court
+#   bash pr-sweep.sh --all            # every open PR with its state
+#   bash pr-sweep.sh --state <path>   # a state file other than the default
 #   bash pr-sweep.sh --help
 #
 # Environment:
 #   HOUSEBROKEN_USER  GitHub login to sweep, default the authenticated user
+#   HOUSEBROKEN_HOME  workshop root, default $HOME/.housebroken. The state file
+#                     is $HOUSEBROKEN_HOME/sweep-state.json unless --state
+#                     says otherwise.
 #
 # 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
@@ -25,12 +33,28 @@ usage() {
 }
 
 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
+STATE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --help|-h) usage; exit 0 ;;
+    --all) ALL=1 ;;
+    --state)
+      shift
+      [ $# -gt 0 ] || { echo "pr-sweep.sh: --state needs a path" >&2; exit 2; }
+      STATE="$1"
+      ;;
+    *) echo "pr-sweep.sh: unknown argument: $1" >&2; usage >&2; exit 2 ;;
+  esac
+  shift
+done
+
+if [ -z "$STATE" ]; then
+  STATE="${HOUSEBROKEN_HOME:-$HOME/.housebroken}/sweep-state.json"
+fi
+if ! mkdir -p "$(dirname "$STATE")"; then
+  echo "pr-sweep.sh: cannot create the directory of $STATE" >&2
+  exit 1
+fi
 
 ME="${HOUSEBROKEN_USER:-$(gh api user --jq .login)}"
 if [ -z "$ME" ]; then
@@ -44,6 +68,45 @@ if ! list="$(gh search prs --author "$ME" --state open --limit 100 --json reposi
   exit 1
 fi
 [ -n "$list" ] || { echo "pr-sweep.sh: no open PRs found for $ME" >&2; exit 1; }
+
+open_ids="$(printf '%s\n' "$list" | tr -d '\r' | awk -F'\t' 'NF > 1 { print $1 "#" $2 }' | sort)"
+if [ -f "$STATE" ]; then
+  # jq on Windows writes CRLF; a stray CR would make every stored id look new
+  if ! last="$(jq -r '.lastRun // "an unknown time"' "$STATE" | tr -d '\r')"; then
+    echo "pr-sweep.sh: cannot read $STATE" >&2
+    exit 1
+  fi
+  echo "--- merged or closed since $last"
+  gone="$(comm -23 <(jq -r '.open[]?' "$STATE" | tr -d '\r' | sort) <(printf '%s\n' "$open_ids"))"
+  while read -r id; do
+    [ -n "$id" ] || continue
+    gone_repo="${id%#*}"; gone_num="${id##*#}"
+    if ! v="$(gh pr view "$gone_num" --repo "$gone_repo" --json state,mergedAt,closedAt,mergedBy)"; then
+      echo "pr-sweep.sh: gh pr view $id failed" >&2
+      continue
+    fi
+    case "$(printf '%s' "$v" | jq -r '.state // "-"' | tr -d '\r')" in
+      MERGED)
+        printf 'MERGED %s by %s at %s\n' "$id" \
+          "$(printf '%s' "$v" | jq -r '.mergedBy.login // "-"' | tr -d '\r')" \
+          "$(printf '%s' "$v" | jq -r '.mergedAt // "-"' | tr -d '\r')"
+        ;;
+      CLOSED)
+        printf 'CLOSED %s at %s\n' "$id" \
+          "$(printf '%s' "$v" | jq -r '.closedAt // "-"' | tr -d '\r')"
+        ;;
+    esac
+  done <<< "$gone"
+else
+  echo "--- no previous sweep recorded"
+fi
+
+if ! printf '%s\n' "$open_ids" | jq -R -s --arg t "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  '{lastRun: $t, open: (split("\n") | map(select(length > 0)))}' > "$STATE"; then
+  echo "pr-sweep.sh: cannot write $STATE" >&2
+  exit 1
+fi
+
 n=0; act=0
 while IFS=$'\t' read -r repo num updated title; do
   [ -n "$repo" ] || continue

{housebroken_cli-0.1.0 → housebroken_cli-0.2.0}/skills/housebroken/SKILL.md

@@ -76,6 +76,8 @@ report it in one line and do not proceed to the next step.
    criteria in machine-readable form; run them.
 
 6. **Match the house style.**
+   Run `housebroken notes owner/repo` before writing the pull request and
+   again before any rework, and follow what is there.
    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,
@@ -113,7 +115,9 @@ report it in one line and do not proceed to the next step.
     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.
+    silent maintainer without the user's explicit word. After answering a
+    review, record what the maintainer asked for with
+    `housebroken notes owner/repo add "..."`.
 
 11. **Clean up.**
     `housebroken hygiene` deletes the fork branch of every merged or closed
@@ -127,12 +131,24 @@ report it in one line and do not proceed to the next step.
     maintainers cap open pull requests from non-collaborators and counts
     agent-opened ones against that cap.
 
+13. **Write it down before you leave.**
+    A run through the door ends with its ledger, not with the pull
+    request. A house rule learned about the repository goes into
+    `housebroken notes owner/repo add "..."` the same session. A
+    maintainer's verdict on a filed pull request is a lesson for everyone:
+    it goes into docs/lessons.md in the housebroken repository the same
+    day, quoted verbatim with the rule it became, by pull request when the
+    repository is not yours. A gate that was wrong, missing, or done by
+    hand goes on the housebroken repository as an issue before the run
+    ends. A lesson that lives only in a chat is lost.
+
 ## 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
+filing: the pull request URL and the verify result. At the end of the run:
+what went into the ledger, or that nothing did. On a refusal at any
 step: which step, and the one sentence that explains it.
 
 ## Never

housebroken_cli-0.2.0/src/housebroken/__init__.py

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

housebroken_cli-0.1.0/scripts/comment-census.sh

@@ -1,83 +0,0 @@
-#!/bin/bash
-# comment-census.sh - added code lines against added comment lines, per branch.
-#
-# A patch that carries a paragraph of comments into a file that has none reads
-# as machine-written and gets closed. This counts, for every branch in every
-# clone under a directory, the added non-comment lines and the added comment
-# lines, so a pull request can be made to match the comment density of the file
-# it lands in. Three maintainers asked for exactly this, in three separate
-# reviews, before it became a script.
-#
-# Usage:
-#   bash comment-census.sh [CLONE_ROOT]
-#   bash comment-census.sh --help
-#
-# CLONE_ROOT is any directory whose immediate subdirectories are git clones.
-# Defaults to $HOUSEBROKEN_CLONES, then to $HOUSEBROKEN_HOME/clones.
-#
-# Environment:
-#   HOUSEBROKEN_CLONES  default clone root
-#   HOUSEBROKEN_HOME    workshop root, default $HOME/.housebroken
-#
-# Assumes: each clone has an origin remote whose default branch is discoverable
-# (origin/HEAD, else origin/main, else origin/master); every other local branch
-# is a candidate patch. Tests, markdown and lock files are excluded from the
-# code and comment counts. Comment detection covers //, /* */, * and #.
-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
-
-HOUSEBROKEN_HOME="${HOUSEBROKEN_HOME:-$HOME/.housebroken}"
-root="${1:-${HOUSEBROKEN_CLONES:-$HOUSEBROKEN_HOME/clones}}"
-
-if [ ! -d "$root" ]; then
-  echo "comment-census.sh: not a directory: $root" >&2
-  echo "give a clone root as an argument or set HOUSEBROKEN_CLONES" >&2
-  exit 1
-fi
-
-printf '%-28s %-36s %5s %5s %5s\n' repo branch code cmnt tests
-
-found=0
-for d in "$root"/*/; do
-  [ -d "$d/.git" ] || continue
-  found=1
-  name=$(basename "$d")
-  base=$(git -C "$d" symbolic-ref -q --short refs/remotes/origin/HEAD || true)
-  if [ -z "$base" ]; then
-    if git -C "$d" rev-parse --verify -q origin/main >/dev/null; then
-      base=origin/main
-    elif git -C "$d" rev-parse --verify -q origin/master >/dev/null; then
-      base=origin/master
-    else
-      echo "comment-census.sh: no default branch in $d, skipped" >&2
-      continue
-    fi
-  fi
-  default_branch="${base#origin/}"
-  while read -r br; do
-    [ -n "$br" ] || continue
-    [ "$br" = "$default_branch" ] && continue
-    [ "$(git -C "$d" rev-list --count "$base..$br")" = "0" ] && continue
-    added=$(git -C "$d" diff "$base..$br" -- . ':(exclude)*test*' ':(exclude)*Test*' ':(exclude)*_test.go' ':(exclude)Tests/*' ':(exclude)*.md' ':(exclude)*.sum' | grep '^+' | grep -v '^+++' || true)
-    if [ -z "$added" ]; then
-      code=0; cmnt=0
-    else
-      code=$(printf '%s\n' "$added" | grep -v -E '^\+\s*(//|/\*|\*|#|///|\*/)' | grep -c -v -E '^\+\s*$' || true)
-      cmnt=$(printf '%s\n' "$added" | grep -c -E '^\+\s*(//|/\*|\*|///|\*/)' || true)
-    fi
-    tests=$(git -C "$d" diff "$base..$br" --numstat | awk '/[Tt]est/{s+=$1} END{print s+0}')
-    printf '%-28s %-36s %5s %5s %5s\n' "$name" "$br" "$code" "$cmnt" "$tests"
-  done < <(git -C "$d" for-each-ref --format='%(refname:short)' refs/heads/)
-done
-
-if [ "$found" = 0 ]; then
-  echo "comment-census.sh: no git clones found under $root" >&2
-  exit 1
-fi

housebroken_cli-0.1.0/src/housebroken/__init__.py

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