feat(kvb-git-commit-next): stage a file by line with stage_hunks.py

stage_hunks.py takes git diff -U0 of one file, keeps the added lines of an add-only hunk that match a regex and every other hunk whole when one of its changed lines matches, and applies the result to the index with git apply --cached --unidiff-zero --recount, or prints it with --dry-run; exit 1 when nothing matches. Step 4 of kvb-git-commit-next names it for a file that carries two bundles, which replaces the hand-written partial patches needed five times on 2026-11-03. tests/test_stage_hunks.py covers matching, the unstaged rest and the exit codes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

skills/kvb-git-commit-next/SKILL.md

@@ -29,7 +29,9 @@ description: >
    see tracked, modified files and read the worktree; only an untracked
    NEW file needs `git add` to become visible. Path-scope every `git add`
    to the bundle — `git add -A` sweeps up the operator's own edits and
-   their local config.
+   their local config. A file that carries two bundles is staged by line:
+   `${CLAUDE_SKILL_DIR}/scripts/stage_hunks.py --repo <worktree> --file
+   <path> --match <regex>`, first with `--dry-run`.
 5. For the newly staged bundle run the kvb-think-explain skill (what the changes do
    and how the pieces interact, file:line-anchored) followed by the
    kvb-check-confidence skill (fix confidence, break risk, evidence, residuals).

skills/kvb-git-commit-next/scripts/stage_hunks.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Stage only the changed lines of one file that match a pattern.
+
+Args:
+    --repo: path of the git worktree.
+    --file: the file, relative to the worktree root.
+    --match: regular expression; a hunk of only added lines keeps the added
+        lines it matches, any other hunk is staged whole when one of its
+        changed lines matches.
+    --dry-run: print the patch instead of applying it to the index.
+
+Exit codes:
+    0 staged or printed, 1 nothing matched, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+def fail(message: str) -> None:
+    print(f"stage_hunks: {message}", file=sys.stderr)
+    sys.exit(2)
+
+
+def git(repo: Path, *args: str, stdin: str | None = None) -> str:
+    result = subprocess.run(
+        ["git", *args], cwd=repo, input=stdin, capture_output=True, text=True, check=False
+    )
+    if result.returncode != 0:
+        fail(result.stderr.strip() or f"git {' '.join(args)} failed")
+    return result.stdout
+
+
+def split(diff: str) -> tuple[list[str], list[list[str]]]:
+    header: list[str] = []
+    hunks: list[list[str]] = []
+    for line in diff.splitlines():
+        if line.startswith("@@"):
+            hunks.append([line])
+        elif hunks:
+            hunks[-1].append(line)
+        else:
+            header.append(line)
+    return header, hunks
+
+
+def select(hunks: list[list[str]], pattern: re.Pattern) -> list[list[str]]:
+    kept = []
+    for hunk in hunks:
+        changes = [line for line in hunk[1:] if line[:1] in "+-"]
+        if all(line.startswith("+") for line in changes):
+            lines = [line for line in changes if pattern.search(line[1:])]
+            if lines:
+                kept.append([hunk[0], *lines])
+        elif any(pattern.search(line[1:]) for line in changes):
+            kept.append(hunk)
+    return kept
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--repo", required=True)
+    parser.add_argument("--file", required=True)
+    parser.add_argument("--match", required=True)
+    parser.add_argument("--dry-run", action="store_true")
+    args = parser.parse_args()
+
+    repo = Path(args.repo)
+    if not repo.is_dir():
+        fail(f"{repo} is not a directory")
+    try:
+        pattern = re.compile(args.match)
+    except re.error as error:
+        fail(f"--match: {error}")
+    header, hunks = split(git(repo, "diff", "--no-color", "-U0", "--", args.file))
+    kept = select(hunks, pattern)
+    if not kept:
+        print(f"stage_hunks: no change in {args.file} matches {args.match!r}", file=sys.stderr)
+        return 1
+    patch = "\n".join([*header, *(line for hunk in kept for line in hunk)]) + "\n"
+    if args.dry_run:
+        print(patch, end="")
+        return 0
+    git(repo, "apply", "--cached", "--unidiff-zero", "--recount", "-", stdin=patch)
+    print(f"staged {sum(len(h) - 1 for h in kept)} lines of {args.file}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())