housebroken-cli 0.2.8__tar.gz → 0.4.0__tar.gz

{housebroken_cli-0.2.8 → housebroken_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: housebroken-cli
-Version: 0.2.8
+Version: 0.4.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
@@ -109,7 +109,7 @@ Every organization gets a card before the first filing: CLA, DCO, signed-commit
 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.
+`branch-check.sh` reads the branch before anything leaves the machine: it refuses a dirty working tree, a file whose mode disagrees with its own siblings, a committed file the repository's own `.gitignore` excludes, a working artifact, and a branch that is not on top of its base, and it prints every absolute claim the added prose makes so each can be falsified against the code. Three of those came from one review round on a single pull request. `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.
@@ -146,6 +146,8 @@ uv tool install git+https://github.com/lenamonj/housebroken
 | `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/claim-check.sh` | every falsifiable claim in a body or a reply, listed to re-derive |
+| `scripts/branch-check.sh` | the branch's mechanical facts: clean tree, file modes, artifacts, absolute claims |
 | `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 |

{housebroken_cli-0.2.8 → housebroken_cli-0.4.0}/README.md

@@ -97,7 +97,7 @@ Every organization gets a card before the first filing: CLA, DCO, signed-commit
 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.
+`branch-check.sh` reads the branch before anything leaves the machine: it refuses a dirty working tree, a file whose mode disagrees with its own siblings, a committed file the repository's own `.gitignore` excludes, a working artifact, and a branch that is not on top of its base, and it prints every absolute claim the added prose makes so each can be falsified against the code. Three of those came from one review round on a single pull request. `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.
@@ -134,6 +134,8 @@ uv tool install git+https://github.com/lenamonj/housebroken
 | `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/claim-check.sh` | every falsifiable claim in a body or a reply, listed to re-derive |
+| `scripts/branch-check.sh` | the branch's mechanical facts: clean tree, file modes, artifacts, absolute claims |
 | `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 |

{housebroken_cli-0.2.8 → housebroken_cli-0.4.0}/bin/housebroken

@@ -1,5 +1,5 @@
 #!/bin/bash
-# housebroken - one command name for the nine gate scripts.
+# housebroken - one command name for the 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 nine *.sh gate scripts. When
+#   HOUSEBROKEN_SCRIPTS  directory holding the *.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.
@@ -48,6 +48,8 @@ usage: housebroken <subcommand> [args...]
   1  outside     count outside contributors merged in the last 120 days
   2  prior-art   issues and pull requests on the touched files, rulings quoted
   6  census      added code lines against added comment lines, per branch
+  6  claims      every falsifiable claim in outbound text, listed to re-derive
+  9  branch      the mechanical facts about the branch: tree, modes, artifacts, claims
   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
@@ -89,6 +91,8 @@ case "$cmd" in
   outside)   script=distinct-outside.sh ;;
   prior-art) script=prior-art.sh ;;
   census)    script=comment-census.sh ;;
+  claims)    script=claim-check.sh ;;
+  branch)    script=branch-check.sh ;;
   file)      script=file-pr.sh ;;
   verify)    script=verify-filed-pr.sh ;;
   sweep)     script=pr-sweep.sh ;;

{housebroken_cli-0.2.8 → housebroken_cli-0.4.0}/pyproject.toml

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

housebroken_cli-0.4.0/scripts/branch-check.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+# branch-check.sh - the mechanical facts about the branch you are about to file.
+#
+# Three defects on PaloAltoNetworks/docusaurus-openapi-docs #1624 were facts
+# about the branch rather than about the patch, and git could have printed all
+# three before anything left the machine.
+#
+# A reviewer had just shown that a sentence in the added documentation
+# overclaimed. The wording was corrected in the working tree, the branch was
+# rebuilt with `git reset --soft <base>`, and the commits still carried the old
+# sentence: a soft reset leaves the index at the previous commit, so the
+# corrected file was never staged. The tree was dirty and nobody looked. A
+# dirty tree is a refusal here, because what you tested is not what you file.
+#
+# The new test file was committed 100755 where every other test in that
+# repository is 100644, which GitHub renders in the diff. A mode that disagrees
+# with the file's own siblings is a refusal.
+#
+# The overclaiming sentence was an absolute: "removes only the files the plugin
+# generated", which the code falsifies for two file names. Absolutes in added
+# prose are printed for you to check one by one; they are not refused, because
+# some of them are true.
+#
+# Usage:
+#   bash branch-check.sh [CLONE] [--base REF]
+#   bash branch-check.sh --help
+#
+# CLONE defaults to the current directory. REF defaults to the first of
+# upstream/main, upstream/master, origin/main, origin/master that resolves.
+#
+# Exits 0 when nothing blocks, 1 on a refusal, 2 on a usage error.
+set -u
+
+usage() { awk 'NR>1 && /^#/ {sub(/^# ?/, ""); print; next} NR>1 {exit}' "$0"; }
+
+clone="."
+base=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --help|-h) usage; exit 0 ;;
+    --base)
+      shift
+      base="${1:-}"
+      [ -n "$base" ] || { echo "REFUSED: --base needs a ref" >&2; exit 2; }
+      ;;
+    -*) echo "REFUSED: unknown option $1" >&2; exit 2 ;;
+    *) clone="$1" ;;
+  esac
+  shift
+done
+
+cd "$clone" 2>/dev/null || { echo "REFUSED: $clone is not a directory" >&2; exit 2; }
+git rev-parse --git-dir >/dev/null 2>&1 || { echo "REFUSED: $clone is not a git clone" >&2; exit 2; }
+
+if [ -z "$base" ]; then
+  for candidate in upstream/main upstream/master origin/main origin/master; do
+    if git rev-parse --verify -q "$candidate" >/dev/null 2>&1; then base="$candidate"; break; fi
+  done
+fi
+[ -n "$base" ] || { echo "REFUSED: no base ref resolved - pass --base REF" >&2; exit 2; }
+git rev-parse --verify -q "$base" >/dev/null 2>&1 || { echo "REFUSED: base $base does not resolve" >&2; exit 2; }
+
+blocked=0
+block() { echo "REFUSED: $*"; blocked=1; }
+
+echo "== branch check: $(git rev-parse --abbrev-ref HEAD) against $base =="
+
+# What you tested is what you file, or you do not know what you are filing.
+dirty=$(git status --porcelain)
+if [ -n "$dirty" ]; then
+  block "the working tree is dirty, so the commits are not what you tested"
+  printf '%s\n' "$dirty" | sed 's/^/    /'
+fi
+
+if ! git merge-base --is-ancestor "$base" HEAD 2>/dev/null; then
+  block "HEAD is not on top of $base - rebase before filing"
+fi
+
+files=$(git diff --name-only "$base..HEAD" 2>/dev/null)
+if [ -z "$files" ]; then
+  block "no files differ from $base - there is nothing to file"
+fi
+
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  entry=$(git ls-files -s -- "$f" 2>/dev/null)
+  [ -n "$entry" ] || continue
+  mode=$(printf '%s\n' "$entry" | awk '{print $1}')
+
+  # A mode is only wrong relative to the file's own neighbours.
+  if [ "$mode" = "100755" ]; then
+    case "$f" in
+      *.*) ext=".${f##*.}" ;;
+      *) ext="" ;;
+    esac
+    if [ -n "$ext" ]; then
+      sibs=$(git ls-files -s -- "*$ext" 2>/dev/null | awk -v self="$f" '$4 != self {print $1}')
+      norm=$(printf '%s\n' "$sibs" | grep -c '^100644$')
+      exec=$(printf '%s\n' "$sibs" | grep -c '^100755$')
+      if [ "$norm" -gt "$exec" ]; then
+        block "$f is committed 100755 but $norm of its $ext siblings are 100644"
+      fi
+    fi
+  fi
+
+  # The repository's own .gitignore is the authority on what is build output.
+  if git check-ignore -q --no-index -- "$f" 2>/dev/null; then
+    block "$f is committed but the repository's .gitignore excludes it"
+  fi
+
+  case "$f" in
+    .jeffy/*|*/.jeffy/*|PLAN.md|*/PLAN.md|JOURNAL.md|*/JOURNAL.md|*.orig|*.rej)
+      block "$f is a working artifact and has no place in the diff" ;;
+  esac
+done <<EOF
+$files
+EOF
+
+# Absolutes in added prose are the claims a maintainer can falsify in one grep.
+claims=$(git diff -U0 "$base..HEAD" -- '*.md' '*.mdx' '*.rst' '*.txt' 2>/dev/null \
+  | grep '^+' | grep -v '^+++' | sed 's/^+//' \
+  | grep -nEi '\b(only|exactly|always|never|guaranteed|nothing|everything)\b')
+if [ -n "$claims" ]; then
+  echo "CHECK: added prose makes absolute claims - falsify each one against the code:"
+  printf '%s\n' "$claims" | sed 's/^/    /'
+fi
+
+echo
+echo "commits:"
+git log --oneline "$base..HEAD" | sed 's/^/    /'
+echo "diff:"
+git diff --stat "$base..HEAD" | sed 's/^/    /'
+
+if [ "$blocked" -ne 0 ]; then
+  echo
+  echo "branch-check: refused. Fix the causes above; a refusal is a result."
+  exit 1
+fi
+echo
+echo "branch-check: nothing mechanical blocks this branch."

housebroken_cli-0.4.0/scripts/claim-check.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# claim-check.sh - lists every claim in outbound text that a maintainer can
+# falsify, so each one gets re-derived before it is sent.
+#
+# On microsoft/GSL #1272 a reply draft said "The five new static_asserts fail on
+# main." A reviewer falsified it in one pass. The number had come from a red arm
+# that grepped only for `static assertion failed`, so it counted five matches
+# and never saw the twenty-one other errors beside them; and against the commit
+# a maintainer would actually revert to, only four of the five fail. The
+# sentence named a basis and was still wrong about it.
+#
+# So this does not try to judge a claim. Text checks cannot: the bad sentence
+# named its revision and read perfectly. It lists them, and the rule in step 6
+# is that every listed line is re-measured, at the moment of writing, against
+# the exact revision the sentence names. The gap this closes is that until now
+# every gate here read code and nothing read the prose, while the prose is what
+# the maintainer reads first.
+#
+# Usage:
+#   bash claim-check.sh FILE
+#   bash claim-check.sh --help
+#
+# Exits 1 when it finds claims to re-derive, 0 when it finds none, 2 on a usage
+# error. Exit 1 is not a refusal to send; it is a refusal to send unread.
+set -u
+
+usage() { awk 'NR>1 && /^#/ {sub(/^# ?/, ""); print; next} NR>1 {exit}' "$0"; }
+
+case "${1:-}" in
+  --help|-h) usage; exit 0 ;;
+  "") echo "REFUSED: name the file holding the text" >&2; exit 2 ;;
+esac
+file="$1"
+[ -f "$file" ] || { echo "REFUSED: $file does not exist" >&2; exit 2; }
+
+# Strip fenced code and quoted logs: a number inside pasted output is evidence,
+# not a claim being made.
+body=$(awk '/^```/ {fence = !fence; next} !fence && !/^ *[|>]/ {print NR": "$0}' "$file")
+
+quantified=$(printf '%s
+' "$body" | grep -nEi '[0-9]+ *(of|/) *[0-9]+|\b([0-9]+|one|two|three|four|five|six|seven|eight|nine|ten|no) +([a-z_-]+ +){0,3}(tests?|assertions?|static_asserts?|checks?|errors?|failures?|jobs?|files?|warnings?|projects?|commits?|suites?)\b' | cut -d: -f2-)
+
+absolute=$(printf '%s\n' "$body" | grep -nEi \
+  '\b(only|exactly|always|never|every|all|none|nothing|everything|guaranteed|any)\b' \
+  | cut -d: -f2-)
+
+found=0
+if [ -n "$quantified" ]; then
+  found=1
+  echo "COUNTED: re-derive each, against the revision the sentence names, now:"
+  printf '%s\n' "$quantified" | sed 's/^/    /'
+fi
+if [ -n "$absolute" ]; then
+  found=1
+  echo "ABSOLUTE: falsify each against the code, not against your memory of it:"
+  printf '%s\n' "$absolute" | sed 's/^/    /'
+fi
+
+if [ "$found" -eq 0 ]; then
+  echo "claim-check: no falsifiable claim found in $file"
+  exit 0
+fi
+echo
+echo "claim-check: $file makes claims a maintainer can check. Re-measure each"
+echo "one before sending. A sentence that names its revision can still be wrong"
+echo "about it; that is the failure this exists for."
+exit 1

{housebroken_cli-0.2.8 → housebroken_cli-0.4.0}/skills/housebroken/SKILL.md

@@ -81,8 +81,15 @@ report it in one line and do not proceed to the next step.
    trusting a command's exit code, check the clone's line endings before the
    first edit, export PATH explicitly in any detached script and report every
    step's exit code. Two arms of an experiment that agree exactly have not
-   tested the variable. Before filing, hash the changed file on disk against
-   the blob in the commit: a branch can carry the test and not the fix. When the
+   tested the variable. Swap the file's content from `git show <base>:<path>`
+   rather than switching branches: a checkout refused because the tree is
+   dirty leaves the patched file in place, and the arm then reports success
+   under the label RED. Assert the two arms' hashes differ before believing
+   either result. Before filing, hash the changed file on disk against
+   the blob in the commit: a branch can carry the test and not the fix.
+   After rebuilding commits, grep the committed blob for the change, never
+   the file on disk: `git reset --soft` leaves the index at the previous
+   commit, so a correction made after that commit is not in the new one. 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
@@ -94,7 +101,11 @@ report it in one line and do not proceed to the next step.
    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.
+   criteria in machine-readable form; run them. When the project's own lint
+   aborts on its own configuration, that is a fact to state, not permission
+   to skip yours: run the linter over the changed files directly, and
+   reproduce the global failure on a pristine base so the body says whose
+   it is.
 
 6. **Match the house style.**
    Run `housebroken notes owner/repo` before writing the pull request and
@@ -107,7 +118,11 @@ report it in one line and do not proceed to the next step.
    you reproduced on the fresh clone in this session, never a line carried
    from a journal. 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.
+   was used, answer in one truthful sentence. Run `housebroken claims` over
+   the body and re-measure every line it lists, now, against the exact
+   revision that sentence names. A claim that names its revision can still
+   be wrong about it, which is why the listing is the whole gate: the
+   re-derivation is yours to do.
 
 7. **Know the paperwork.**
    Before the first pull request to an organization, find its agreement: CLA,
@@ -124,7 +139,12 @@ report it in one line and do not proceed to the next step.
    pull request until the project answers.
 
 9. **File through the gate.**
-   `housebroken file owner/repo --title ... --body-file ...` is the only way a
+   `housebroken branch <clone>` first. It refuses a dirty working tree, a file
+   whose mode disagrees with its own siblings, a committed file the repository
+   ignores, and a branch that is not on top of its base, and it prints every
+   absolute claim your added prose makes so you can falsify each one against
+   the code. Then
+   `housebroken file owner/repo --title ... --body-file ...`, 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
@@ -141,7 +161,9 @@ report it in one line and do not proceed to the next step.
     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
+    in the user's voice, and run `housebroken claims` over the reply before
+    it is posted: the only claim that has gone out wrong here was in a
+    reply, not a body. 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