housebroken-cli 0.2.7__tar.gz → 0.3.0__tar.gz

{housebroken_cli-0.2.7 → housebroken_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: housebroken-cli
-Version: 0.2.7
+Version: 0.3.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,7 @@ 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/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.7 → housebroken_cli-0.3.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,7 @@ 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/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.7 → housebroken_cli-0.3.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,7 @@ 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
+  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 +90,7 @@ case "$cmd" in
   outside)   script=distinct-outside.sh ;;
   prior-art) script=prior-art.sh ;;
   census)    script=comment-census.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.7 → housebroken_cli-0.3.0}/pyproject.toml

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

housebroken_cli-0.3.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.2.7 → housebroken_cli-0.3.0}/skills/housebroken/SKILL.md

@@ -71,11 +71,25 @@ report it in one line and do not proceed to the next step.
    that fails on the default branch for a wrong value, a crash or an
    out-of-bounds access, and "less memory" is not that test.
 
-4. **Prove it red first.**
+4. **Prove it red first, and prove the proof.**
    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. When the
+   the test itself; the body states the fact in one sentence.
+   Ask what each step would print if it did nothing, and make that answer
+   different from success: revert by content and compare hashes rather than
+   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. 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
@@ -87,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
@@ -117,7 +135,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