housebroken-cli 0.2.1__tar.gz → 0.2.3__tar.gz

{housebroken_cli-0.2.1 → housebroken_cli-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: housebroken-cli
-Version: 0.2.1
+Version: 0.2.3
 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

{housebroken_cli-0.2.1 → housebroken_cli-0.2.3}/bin/housebroken

@@ -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  inbox       what GitHub has to tell you since you last looked, bodies included
  10  notes       what this repository's maintainers have asked for before
  11  hygiene     delete fork branches after merge or close, list orphan forks
 
@@ -91,6 +92,7 @@ case "$cmd" in
   file)      script=file-pr.sh ;;
   verify)    script=verify-filed-pr.sh ;;
   sweep)     script=pr-sweep.sh ;;
+  inbox)     script=inbox.sh ;;
   notes)     script=notes.sh ;;
   hygiene)   script=fork-hygiene.sh ;;
   *)

{housebroken_cli-0.2.1 → housebroken_cli-0.2.3}/pyproject.toml

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

housebroken_cli-0.2.3/scripts/inbox.sh

@@ -0,0 +1,137 @@
+#!/bin/bash
+# inbox.sh - what GitHub has to tell you since you last looked, bodies included.
+#
+# A commenter list is not a read. This prints every notification on the
+# threads you are subscribed to (everything you authored) newer than a cursor,
+# expands each to the full text of its latest comment or review, states the
+# thread's current state (open, draft, merged, closed), and then takes a census
+# of every open pull request of yours for failing, blocked or conflicting
+# checks, which the notification feed does not carry for upstream pulls.
+# Written 2026-09-08 after a two-bug review on apache/commons-lang #1783 sat
+# unread for forty minutes because a check printed who had commented instead
+# of what they said, and after cisco/libsrtp #821 sat red for two days with
+# nobody reading its checks.
+#
+# The cursor is a timestamp, not GitHub's unread flag: reading a thread on the
+# phone marks it read, and that must not hide it from the desk.
+#
+# Usage:
+#   bash inbox.sh                   # since the stored cursor (first run: 24 h ago)
+#   bash inbox.sh --since <ISO8601> # since an explicit time, cursor untouched
+#   bash inbox.sh --no-ci           # skip the census of open pull requests
+#   bash inbox.sh --ack             # store now as the cursor; run after acting
+#   bash inbox.sh --help
+#
+# Environment:
+#   HOUSEBROKEN_USER  your GitHub login, default the authenticated user
+#   HOUSEBROKEN_HOME  workshop root, default $HOME/.housebroken; the cursor
+#                     lives at $HOUSEBROKEN_HOME/inbox-cursor and every run is
+#                     appended to $HOUSEBROKEN_HOME/inbox-ledger.md
+#
+# Assumes: gh is installed and authenticated with the notifications scope, jq
+# is on PATH. Read-only apart from the cursor and the ledger. Exits non-zero
+# when gh fails.
+set -u
+
+usage() { sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//'; }
+
+home="${HOUSEBROKEN_HOME:-$HOME/.housebroken}"
+cursor_file="$home/inbox-cursor"
+ledger="$home/inbox-ledger.md"
+since=""
+do_ci=1
+ack=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --help|-h) usage; exit 0 ;;
+    --since) shift; since="${1:-}"; [ -n "$since" ] || { echo "inbox.sh: --since needs a time" >&2; exit 2; } ;;
+    --no-ci) do_ci=0 ;;
+    --ack) ack=1 ;;
+    *) echo "inbox.sh: unknown argument $1" >&2; usage >&2; exit 2 ;;
+  esac
+  shift
+done
+
+now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+if [ "$ack" -eq 1 ]; then
+  mkdir -p "$home" && printf '%s\n' "$now" > "$cursor_file" && echo "inbox cursor is now $now" && exit 0
+  echo "inbox.sh: could not write $cursor_file" >&2; exit 1
+fi
+
+user="${HOUSEBROKEN_USER:-$(gh api user --jq .login 2>/dev/null)}"
+[ -n "$user" ] || { echo "inbox.sh: gh is not authenticated" >&2; exit 1; }
+if [ -z "$since" ]; then
+  if [ -s "$cursor_file" ]; then since="$(head -1 "$cursor_file")"; else since="$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-24H +%Y-%m-%dT%H:%M:%SZ)"; fi
+fi
+
+is_bot() { case "$1" in *"[bot]"|copilot-pull-request-reviewer|codecov-commenter|coveralls|CLAassistant|meta-cla*|vercel*|coderabbitai*|copy-pr-bot*|oracle-contributor-agreement*|dependabot*|github-actions*|sonarcloud*|netlify*) return 0 ;; *) return 1 ;; esac; }
+
+echo "== inbox for $user since $since (now $now) =="
+if ! feed="$(gh api "notifications?all=true&since=$since&per_page=100" --paginate 2>/dev/null)"; then
+  echo "inbox.sh: gh api notifications failed (is the notifications scope granted?)" >&2; exit 1
+fi
+threads="$(printf '%s' "$feed" | jq -c '.[] | select(.subject.type == "PullRequest" or .subject.type == "Issue") | {repo: .repository.full_name, type: .subject.type, num: (.subject.url | split("/") | last), title: .subject.title, reason: .reason, at: .updated_at, latest: (.subject.latest_comment_url // "")}' | sort -u)"
+count=$(printf '%s\n' "$threads" | grep -c . || true)
+human=0
+echo "$count thread(s) with activity"
+while IFS= read -r t; do
+  [ -n "$t" ] || continue
+  repo=$(jq -r .repo <<<"$t"); num=$(jq -r .num <<<"$t"); type=$(jq -r .type <<<"$t"); reason=$(jq -r .reason <<<"$t"); at=$(jq -r .at <<<"$t"); latest=$(jq -r .latest <<<"$t"); title=$(jq -r .title <<<"$t")
+  if [ "$type" = "PullRequest" ]; then
+    state=$(gh pr view "$num" --repo "$repo" --json state,isDraft,mergedBy --jq 'if .state == "MERGED" then "MERGED by " + (.mergedBy.login // "?") elif .isDraft then "OPEN, DRAFT" else .state end' 2>/dev/null || echo "?")
+  else
+    state=$(gh issue view "$num" --repo "$repo" --json state --jq .state 2>/dev/null || echo "?")
+  fi
+  echo
+  echo "--- $repo#$num [$reason, $at] $state"
+  echo "    $title"
+  if [ -n "$latest" ]; then
+    if c="$(gh api "$latest" 2>/dev/null)"; then
+      who=$(jq -r '.user.login // "?"' <<<"$c"); when=$(jq -r '.created_at // .submitted_at // ""' <<<"$c"); where=$(jq -r 'if .path then " on " + .path + ":" + ((.line // .original_line // 0)|tostring) else "" end' <<<"$c"); rstate=$(jq -r '.state // ""' <<<"$c")
+      if [ "$who" = "$user" ]; then
+        echo "    latest: yours, $when"
+      elif is_bot "$who"; then
+        echo "    latest: $who (bot), $when$where"
+      else
+        human=$((human + 1))
+        echo "    latest: $who, $when$where${rstate:+ [$rstate]}"
+        jq -r '.body // ""' <<<"$c" | sed 's/^/    | /'
+      fi
+    else
+      echo "    latest comment could not be fetched: $latest"
+    fi
+  else
+    echo "    (no comment attached: a review, a merge, a close, a mention or a review request; see the state above)"
+    if [ "$type" = "PullRequest" ]; then
+      gh api "repos/$repo/pulls/$num/reviews?per_page=100" --jq --arg since "$since" --arg me "$user" '.[] | select(.submitted_at > $since and .user.login != $me) | "    review " + .state + " by " + .user.login + ", " + .submitted_at + (if (.body // "") != "" then "\n    | " + (.body | gsub("\r\n"; "\n    | ")) else "" end)' 2>/dev/null
+    fi
+  fi
+done <<<"$threads"
+
+if [ "$do_ci" -eq 1 ]; then
+  echo
+  echo "== census of open pull requests: failing, blocked, conflicting, changes requested, draft =="
+  prs="$(gh search prs --author "$user" --state open --limit 100 --json repository,number,isDraft --jq '.[] | "\(.repository.nameWithOwner) \(.number) \(.isDraft)"' 2>/dev/null)"
+  total=$(printf '%s\n' "$prs" | grep -c . || true)
+  flagged=0
+  while read -r repo num draft; do
+    [ -n "$repo" ] || continue
+    j="$(gh pr view "$num" --repo "$repo" --json mergeable,reviewDecision,statusCheckRollup 2>/dev/null)" || continue
+    why="$(jq -r --arg draft "$draft" '
+      [ ( [.statusCheckRollup[]? | (.conclusion // .state // "")] | if any(. == "FAILURE" or . == "ERROR") then "FAILING" elif any(. == "ACTION_REQUIRED") then "needs-run-approval" else empty end ),
+        ( if .mergeable == "CONFLICTING" then "CONFLICTING" else empty end ),
+        ( if .reviewDecision == "CHANGES_REQUESTED" then "changes-requested" else empty end ),
+        ( if $draft == "true" then "draft" else empty end ) ] | join(" ")' <<<"$j")"
+    if [ -n "$why" ]; then
+      flagged=$((flagged + 1))
+      fails="$(jq -r '[.statusCheckRollup[]? | select((.conclusion // .state // "") == "FAILURE" or (.conclusion // .state // "") == "ERROR") | (.name // .context)] | unique | join(", ")' <<<"$j")"
+      echo "$repo#$num: $why${fails:+  [$fails]}"
+    fi
+  done <<<"$prs"
+  echo "$flagged of $total open pull requests flagged"
+fi
+
+echo
+echo "$human human item(s) since $since. Act on each, then: housebroken inbox --ack"
+mkdir -p "$home" 2>/dev/null && { echo "## $now (since $since): $count thread(s), $human human"; } >> "$ledger"
+exit 0

{housebroken_cli-0.2.1 → housebroken_cli-0.2.3}/skills/housebroken/SKILL.md

@@ -68,7 +68,11 @@ report it in one line and do not proceed to the next step.
    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.
+   the test itself; the body states the fact in one sentence. When the
+   patched function serves several public entry points or has several
+   branches, the test is a grid: every entry point through every branch,
+   plus the zero, identity and signed-boundary rows. A reviewer lists the
+   empty cells otherwise.
 
 5. **Run their CI, not yours.**
    Run the project's own test target on the fresh clone, and every gate its
@@ -116,13 +120,34 @@ report it in one line and do not proceed to the next step.
     `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
+    is in your court. `housebroken inbox` is the first thing a session does
+    and the only way you learn a thread's state: it prints every event on
+    your threads since the last acknowledged cursor with the full body, the
+    thread's state, and a census of failing, blocked and conflicting checks
+    on every open pull request. A list of who commented is not a read, and a
+    conversion to draft is a review. Act on every human item, then run
+    `housebroken inbox --ack`. Answer every maintainer comment the same day,
+    in the user's voice. 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. After answering a
     review, record what the maintainer asked for with
     `housebroken notes owner/repo add "..."`.
+    Write the reply the way one maintainer writes to another. Lead with the
+    fact or the action, never with a verdict on the reviewer: no "you are
+    right", "good catch", "great point", "thanks for the feedback", no
+    apology, no restating their question, no closing summary or offer of
+    further help. A concession is the corrected fact followed by what
+    changed: "Every loader checks its read, so a truncated file fails on
+    main; the description is corrected." A disagreement is the command and
+    its result, without adjectives. An answer to a question is the answer
+    first and the evidence second. One to three sentences, no bullet list
+    under a paragraph's worth of content, no bold, no exclamation mark, no
+    handle unless the thread has several people. Offer closure as a plain
+    statement ("Fine to close."), and stop when the content stops.
+    Never post two replies to one repository in the same minute: space them
+    at least ten minutes apart, the one that matters most first, so a
+    maintainer's inbox does not show three answers stamped the same second.
 
 11. **Clean up.**
     `housebroken hygiene` deletes the fork branch of every merged or closed
@@ -135,6 +160,8 @@ report it in one line and do not proceed to the next step.
     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.
+    The same spacing applies to filing: pull requests and issues on one
+    repository go out at least ten minutes apart, the strongest first.
 
 13. **Write it down before you leave.**
     A run through the door ends with its ledger, not with the pull