git-hunk 0.3.0__tar.gz → 0.4.0__tar.gz

{git_hunk-0.3.0 → git_hunk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: git-hunk
-Version: 0.3.0
+Version: 0.4.0
 Summary: Non-interactive, programmatic git hunk staging with durable Hunk IDs.
 Project-URL: Homepage, https://github.com/wkentaro/git-hunk
 Project-URL: Issues, https://github.com/wkentaro/git-hunk/issues
@@ -41,6 +41,9 @@ Conditional IDs.
 
 <img src="https://raw.githubusercontent.com/wkentaro/git-hunk/main/assets/teaser.png" alt="git-hunk teaser" width="800">
 
+[Comparison](#comparison) • [Install](#install) • [For AI agents](#for-ai-agents) •
+[Quick start](#quick-start) • [Usage](#usage) • [JSON output](#json-output)
+
 ## Why?
 
 `git add -p` requires interactive input. That makes it unusable for:
@@ -52,38 +55,46 @@ Conditional IDs.
 `git-hunk` solves this by assigning each staged or unstaged Hunk a durable ID
 and exposing simple stage/unstage/discard commands.
 
-## Eval
+## Comparison
+
+| | Interactive | Programmatic | Hunk IDs | Line-level control | JSON output |
+| ---------------- | ----------- | ------------ | -------- | ------------------ | ----------- |
+| `git add -p` | Yes | No | No | Yes | No |
+| `git add <file>` | No | Yes | No | No | No |
+| **`git-hunk`** | **No** | **Yes** | **Yes** | **Yes** | **Yes** |
+
+### Eval
 
 One agent (Claude Code 2.1.226, `claude-sonnet-5`, reasoning effort `high`)
-attempted the same eight tasks from identical repository state, three times per
+attempted the same eight tasks from identical repository state, five times per
 variant: organize a dirty working tree into correct, focused commits, once
 following git-hunk's bundled skills and once restricted to bare Git. The
-[checked-in eval harness](https://github.com/wkentaro/git-hunk/tree/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval)
+[checked-in eval harness](https://github.com/wkentaro/git-hunk/tree/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval)
 grades the exact resulting repository state — commit partition and order, final
 tree, index, and leftovers. This table records the qualifying run; `make eval`
 reruns the protocol and prints a table in the same format.
 
-| Task                                                                                                                                                    | git-hunk                            | bare Git                                        |
+| Task | git-hunk | bare Git |
 | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------- |
-| [split_refactor_vs_feature](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/split_refactor_vs_feature.py) | PASS 3/3 · 3c · 4t                  | PASS 3/3 · 3c [2-3] · 4t [3-4]                  |
-| [separate_mixed_hunks](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/separate_mixed_hunks.py)           | PASS 3/3 · 3c [3-4] · 4t [4-5]      | MIXED 1/3 partition · 15c [11-20] · 16t [12-21] |
-| [drop_debug_lines](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/drop_debug_lines.py)                   | PASS 3/3 · 3c · 4t                  | MIXED 2/3 partition · 16c [8-19] · 17t [9-20]   |
-| [protect_unrelated_work](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/protect_unrelated_work.py)       | PASS 3/3 · 3c · 4t                  | PASS 3/3 · 2c [2-3] · 3t [3-4]                  |
-| [split_single_hunk](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/split_single_hunk.py)                 | PASS 3/3 · 5c [3-5] · 6t [4-6]      | PASS 3/3 · 14c [9-15] · 15t [10-16]             |
-| [separate_formatter_noise](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/separate_formatter_noise.py)   | PASS 3/3 · 4c [3-4] · 5t [4-5]      | PASS 3/3 · 16c [9-30] · 17t [10-31]             |
-| [pick_duplicate_hunk](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/pick_duplicate_hunk.py)             | PASS 3/3 · 3c · 4t                  | PASS 3/3 · 10c [9-17] · 11t [10-18]             |
-| [commit_parseable_subset](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/commit_parseable_subset.py)     | PASS 3/3 · 5c [3-6] · 6t [4-7]      | PASS 3/3 · 14c [12-15] · 15t [13-16]            |
-| **total**                                                                                                                                               | **8/8 · 29c [24-31] · 37t [32-39]** | **6/8 (2 mixed) · 90c [62-122] · 98t [70-130]** |
-
-`c` = tool calls, `t` = turns; a cell reports the median of its three repeats
+| [split_refactor_vs_feature](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/split_refactor_vs_feature.py) | PASS 5/5 · 3c · 4t | PASS 5/5 · 3c [2-5] · 4t [3-6] |
+| [separate_mixed_hunks](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/separate_mixed_hunks.py) | PASS 5/5 · 3c · 4t | PASS 5/5 · 8c [7-12] · 9t [8-13] |
+| [drop_debug_lines](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/drop_debug_lines.py) | PASS 5/5 · 3c [3-4] · 4t [4-5] | MIXED 4/5 partition · 8c [7-27] · 9t [8-28] |
+| [protect_unrelated_work](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/protect_unrelated_work.py) | PASS 5/5 · 3c · 4t | PASS 5/5 · 3c [3-4] · 4t [4-5] |
+| [split_single_hunk](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/split_single_hunk.py) | PASS 5/5 · 4c [3-4] · 5t [4-5] | PASS 5/5 · 11c [9-19] · 12t [10-20] |
+| [separate_formatter_noise](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/separate_formatter_noise.py) | PASS 5/5 · 4c [4-6] · 5t [5-7] | PASS 5/5 · 13c [12-16] · 14t [13-17] |
+| [pick_duplicate_hunk](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/pick_duplicate_hunk.py) | PASS 5/5 · 3c · 4t | PASS 5/5 · 8c [7-25] · 9t [8-26] |
+| [commit_parseable_subset](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/commit_parseable_subset.py) | PASS 5/5 · 4c [3-5] · 5t [4-6] | MIXED 4/5 partition · 13c [10-23] · 14t [11-24] |
+| **total** | **8/8 · 27c [25-31] · 35t [33-39]** | **6/8 (2 mixed) · 67c [57-131] · 75t [65-139]** |
+
+`c` = tool calls, `t` = turns; a cell reports the median of its five repeats
 with the observed range in brackets, dropped where every repeat agreed, and the
-pass column counts passing repeats. `MIXED j/3` means the variant passed j of its
-three repeats, and `partition` names the failure: the commits made do not match
+pass column counts passing repeats. `MIXED j/5` means the variant passed j of its
+five repeats, and `partition` names the failure: the commits made do not match
 the required change groups. The cost column is omitted: bare Git runs second in
 each pair and partly reads the prompt cache the git-hunk run warmed, so raw costs
 are not order-neutral
-([#224](https://github.com/wkentaro/git-hunk/issues/224)). Three samples per task
-variant, dated 2026-08-09 at commit `9829b7a`.
+([#224](https://github.com/wkentaro/git-hunk/issues/224)). Five samples per task
+variant, dated 2026-08-10 at commit `0ef14be`.
 
 ## Install
 
@@ -303,32 +314,32 @@ body; `show --json` adds a structured `lines` array. A `show --json` hunk
 }
 ```
 
-| Field            | Type           | Description                                                                                                                                                                            |
+| Field | Type | Description |
 | ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `schema_version` | int            | Envelope version; bumped on any incompatible change to the shape below.                                                                                                                |
-| `hunks`          | array          | The hunks (empty array when there are no changes).                                                                                                                                     |
-| `id`             | string         | Full canonical SHA-256 Hunk ID; empty for an `untracked` entry, which no command can address. Human output uses a unique prefix of at least seven characters.                          |
-| `id_stability`   | string         | `stable` or `conditional`. An untracked inventory entry reports `stable`, but its empty `id` remains unaddressable.                                                                    |
-| `file`           | union          | Repository path of the changed file, as a byte-safe `{text\|bytes}` union (see below).                                                                                                 |
-| `status`         | string         | One of `staged`, `unstaged`, `untracked`.                                                                                                                                              |
-| `change_kind`    | string         | Git status letter: `A` added, `D` deleted, `M` modified, `T` typechange (`R`/`C` reserved and currently rejected). Always present.                                                     |
-| `a_mode`         | string \| null | 6-digit octal git mode on the pre-image side; `null` when that side does not exist.                                                                                                    |
-| `b_mode`         | string \| null | 6-digit octal git mode on the post-image side; `null` when that side does not exist.                                                                                                   |
-| `binary`         | bool           | Whether the change is binary. Always present.                                                                                                                                          |
-| `header`         | string \| null | The bare `@@ -a,b +c,d @@` range for a text hunk; `null` for a whole-file hunk (binary, mode-only, type, or empty tracked file change) or an `untracked` inventory entry.              |
-| `context_before` | union \| null  | The function/section name after a text hunk's `@@` header, as a `{text\|bytes}` union; `null` for a text hunk without a heading, a whole-file hunk, or an `untracked` inventory entry. |
-| `additions`      | int            | Number of added lines.                                                                                                                                                                 |
-| `deletions`      | int            | Number of removed lines.                                                                                                                                                               |
-| `lines`          | array          | `show --json` only. The structured body; `[]` for a whole-file hunk. See below.                                                                                                        |
+| `schema_version` | int | Envelope version; bumped on any incompatible change to the shape below. |
+| `hunks` | array | The hunks (empty array when there are no changes). |
+| `id` | string | Full canonical SHA-256 Hunk ID; empty for an `untracked` entry, which no command can address. Human output uses a unique prefix of at least seven characters. |
+| `id_stability` | string | `stable` or `conditional`. An untracked inventory entry reports `stable`, but its empty `id` remains unaddressable. |
+| `file` | union | Repository path of the changed file, as a byte-safe `{text\|bytes}` union (see below). |
+| `status` | string | One of `staged`, `unstaged`, `untracked`. |
+| `change_kind` | string | Git status letter: `A` added, `D` deleted, `M` modified, `T` typechange (`R`/`C` reserved and currently rejected). Always present. |
+| `a_mode` | string | null | 6-digit octal git mode on the pre-image side; `null` when that side does not exist. |
+| `b_mode` | string | null | 6-digit octal git mode on the post-image side; `null` when that side does not exist. |
+| `binary` | bool | Whether the change is binary. Always present. |
+| `header` | string | null | The bare `@@ -a,b +c,d @@` range for a text hunk; `null` for a whole-file hunk (binary, mode-only, type, or empty tracked file change) or an `untracked` inventory entry. |
+| `context_before` | union | null | The function/section name after a text hunk's `@@` header, as a `{text\|bytes}` union; `null` for a text hunk without a heading, a whole-file hunk, or an `untracked` inventory entry. |
+| `additions` | int | Number of added lines. |
+| `deletions` | int | Number of removed lines. |
+| `lines` | array | `show --json` only. The structured body; `[]` for a whole-file hunk. See below. |
 
 A `lines` entry is `{ "n", "op", "content", "no_newline"? }`:
 
-| Field        | Type   | Description                                                                                         |
+| Field | Type | Description |
 | ------------ | ------ | --------------------------------------------------------------------------------------------------- |
-| `n`          | int    | 1-based position within the hunk body — the index `-l` line selection uses. Counts every body line. |
-| `op`         | string | `" "` context, `"+"` addition, `"-"` deletion.                                                      |
-| `content`    | union  | The line text **without** its leading op character, as a `{text\|bytes}` union.                     |
-| `no_newline` | bool   | Present and `true` only when the line has no trailing newline; consumes no `n`.                     |
+| `n` | int | 1-based position within the hunk body — the index `-l` line selection uses. Counts every body line. |
+| `op` | string | `" "` context, `"+"` addition, `"-"` deletion. |
+| `content` | union | The line text **without** its leading op character, as a `{text\|bytes}` union. |
+| `no_newline` | bool | Present and `true` only when the line has no trailing newline; consumes no `n`. |
 
 Any field carrying arbitrary git/source bytes (`file`, `context_before`,
 `lines[].content`) is a byte-safe `{text | bytes}` union: `{"text": "..."}` for
@@ -339,14 +350,6 @@ Adding a new field is backward-compatible and does not change `schema_version`;
 renaming, removing, or changing the type of an existing field bumps it. (Before
 `schema_version` existed, `list --json` returned a bare array.)
 
-## Comparison
-
-|                  | Interactive | Programmatic | Hunk IDs | Line-level control | JSON output |
-| ---------------- | ----------- | ------------ | -------- | ------------------ | ----------- |
-| `git add -p`     | Yes         | No           | No       | Yes                | No          |
-| `git add <file>` | No          | Yes          | No       | No                 | No          |
-| **`git-hunk`**   | **No**      | **Yes**      | **Yes**  | **Yes**            | **Yes**     |
-
 ## How it works
 
 1. Rejects detected rename, copy, and unmerged states.

{git_hunk-0.3.0 → git_hunk-0.4.0}/README.md

@@ -13,6 +13,9 @@ Conditional IDs.
 
 <img src="assets/teaser.png" alt="git-hunk teaser" width="800">
 
+[Comparison](#comparison) • [Install](#install) • [For AI agents](#for-ai-agents) •
+[Quick start](#quick-start) • [Usage](#usage) • [JSON output](#json-output)
+
 ## Why?
 
 `git add -p` requires interactive input. That makes it unusable for:
@@ -24,38 +27,46 @@ Conditional IDs.
 `git-hunk` solves this by assigning each staged or unstaged Hunk a durable ID
 and exposing simple stage/unstage/discard commands.
 
-## Eval
+## Comparison
+
+| | Interactive | Programmatic | Hunk IDs | Line-level control | JSON output |
+| ---------------- | ----------- | ------------ | -------- | ------------------ | ----------- |
+| `git add -p` | Yes | No | No | Yes | No |
+| `git add <file>` | No | Yes | No | No | No |
+| **`git-hunk`** | **No** | **Yes** | **Yes** | **Yes** | **Yes** |
+
+### Eval
 
 One agent (Claude Code 2.1.226, `claude-sonnet-5`, reasoning effort `high`)
-attempted the same eight tasks from identical repository state, three times per
+attempted the same eight tasks from identical repository state, five times per
 variant: organize a dirty working tree into correct, focused commits, once
 following git-hunk's bundled skills and once restricted to bare Git. The
-[checked-in eval harness](https://github.com/wkentaro/git-hunk/tree/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval)
+[checked-in eval harness](https://github.com/wkentaro/git-hunk/tree/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval)
 grades the exact resulting repository state — commit partition and order, final
 tree, index, and leftovers. This table records the qualifying run; `make eval`
 reruns the protocol and prints a table in the same format.
 
-| Task                                                                                                                                                    | git-hunk                            | bare Git                                        |
+| Task | git-hunk | bare Git |
 | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------- |
-| [split_refactor_vs_feature](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/split_refactor_vs_feature.py) | PASS 3/3 · 3c · 4t                  | PASS 3/3 · 3c [2-3] · 4t [3-4]                  |
-| [separate_mixed_hunks](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/separate_mixed_hunks.py)           | PASS 3/3 · 3c [3-4] · 4t [4-5]      | MIXED 1/3 partition · 15c [11-20] · 16t [12-21] |
-| [drop_debug_lines](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/drop_debug_lines.py)                   | PASS 3/3 · 3c · 4t                  | MIXED 2/3 partition · 16c [8-19] · 17t [9-20]   |
-| [protect_unrelated_work](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/protect_unrelated_work.py)       | PASS 3/3 · 3c · 4t                  | PASS 3/3 · 2c [2-3] · 3t [3-4]                  |
-| [split_single_hunk](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/split_single_hunk.py)                 | PASS 3/3 · 5c [3-5] · 6t [4-6]      | PASS 3/3 · 14c [9-15] · 15t [10-16]             |
-| [separate_formatter_noise](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/separate_formatter_noise.py)   | PASS 3/3 · 4c [3-4] · 5t [4-5]      | PASS 3/3 · 16c [9-30] · 17t [10-31]             |
-| [pick_duplicate_hunk](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/pick_duplicate_hunk.py)             | PASS 3/3 · 3c · 4t                  | PASS 3/3 · 10c [9-17] · 11t [10-18]             |
-| [commit_parseable_subset](https://github.com/wkentaro/git-hunk/blob/9829b7ac6fd871cd874d47e7424c9082bd58dbaf/eval/tasks/commit_parseable_subset.py)     | PASS 3/3 · 5c [3-6] · 6t [4-7]      | PASS 3/3 · 14c [12-15] · 15t [13-16]            |
-| **total**                                                                                                                                               | **8/8 · 29c [24-31] · 37t [32-39]** | **6/8 (2 mixed) · 90c [62-122] · 98t [70-130]** |
-
-`c` = tool calls, `t` = turns; a cell reports the median of its three repeats
+| [split_refactor_vs_feature](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/split_refactor_vs_feature.py) | PASS 5/5 · 3c · 4t | PASS 5/5 · 3c [2-5] · 4t [3-6] |
+| [separate_mixed_hunks](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/separate_mixed_hunks.py) | PASS 5/5 · 3c · 4t | PASS 5/5 · 8c [7-12] · 9t [8-13] |
+| [drop_debug_lines](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/drop_debug_lines.py) | PASS 5/5 · 3c [3-4] · 4t [4-5] | MIXED 4/5 partition · 8c [7-27] · 9t [8-28] |
+| [protect_unrelated_work](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/protect_unrelated_work.py) | PASS 5/5 · 3c · 4t | PASS 5/5 · 3c [3-4] · 4t [4-5] |
+| [split_single_hunk](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/split_single_hunk.py) | PASS 5/5 · 4c [3-4] · 5t [4-5] | PASS 5/5 · 11c [9-19] · 12t [10-20] |
+| [separate_formatter_noise](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/separate_formatter_noise.py) | PASS 5/5 · 4c [4-6] · 5t [5-7] | PASS 5/5 · 13c [12-16] · 14t [13-17] |
+| [pick_duplicate_hunk](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/pick_duplicate_hunk.py) | PASS 5/5 · 3c · 4t | PASS 5/5 · 8c [7-25] · 9t [8-26] |
+| [commit_parseable_subset](https://github.com/wkentaro/git-hunk/blob/0ef14bef657e187b5ab7283b0dbd64751a02736f/eval/tasks/commit_parseable_subset.py) | PASS 5/5 · 4c [3-5] · 5t [4-6] | MIXED 4/5 partition · 13c [10-23] · 14t [11-24] |
+| **total** | **8/8 · 27c [25-31] · 35t [33-39]** | **6/8 (2 mixed) · 67c [57-131] · 75t [65-139]** |
+
+`c` = tool calls, `t` = turns; a cell reports the median of its five repeats
 with the observed range in brackets, dropped where every repeat agreed, and the
-pass column counts passing repeats. `MIXED j/3` means the variant passed j of its
-three repeats, and `partition` names the failure: the commits made do not match
+pass column counts passing repeats. `MIXED j/5` means the variant passed j of its
+five repeats, and `partition` names the failure: the commits made do not match
 the required change groups. The cost column is omitted: bare Git runs second in
 each pair and partly reads the prompt cache the git-hunk run warmed, so raw costs
 are not order-neutral
-([#224](https://github.com/wkentaro/git-hunk/issues/224)). Three samples per task
-variant, dated 2026-08-09 at commit `9829b7a`.
+([#224](https://github.com/wkentaro/git-hunk/issues/224)). Five samples per task
+variant, dated 2026-08-10 at commit `0ef14be`.
 
 ## Install
 
@@ -275,32 +286,32 @@ body; `show --json` adds a structured `lines` array. A `show --json` hunk
 }
 ```
 
-| Field            | Type           | Description                                                                                                                                                                            |
+| Field | Type | Description |
 | ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `schema_version` | int            | Envelope version; bumped on any incompatible change to the shape below.                                                                                                                |
-| `hunks`          | array          | The hunks (empty array when there are no changes).                                                                                                                                     |
-| `id`             | string         | Full canonical SHA-256 Hunk ID; empty for an `untracked` entry, which no command can address. Human output uses a unique prefix of at least seven characters.                          |
-| `id_stability`   | string         | `stable` or `conditional`. An untracked inventory entry reports `stable`, but its empty `id` remains unaddressable.                                                                    |
-| `file`           | union          | Repository path of the changed file, as a byte-safe `{text\|bytes}` union (see below).                                                                                                 |
-| `status`         | string         | One of `staged`, `unstaged`, `untracked`.                                                                                                                                              |
-| `change_kind`    | string         | Git status letter: `A` added, `D` deleted, `M` modified, `T` typechange (`R`/`C` reserved and currently rejected). Always present.                                                     |
-| `a_mode`         | string \| null | 6-digit octal git mode on the pre-image side; `null` when that side does not exist.                                                                                                    |
-| `b_mode`         | string \| null | 6-digit octal git mode on the post-image side; `null` when that side does not exist.                                                                                                   |
-| `binary`         | bool           | Whether the change is binary. Always present.                                                                                                                                          |
-| `header`         | string \| null | The bare `@@ -a,b +c,d @@` range for a text hunk; `null` for a whole-file hunk (binary, mode-only, type, or empty tracked file change) or an `untracked` inventory entry.              |
-| `context_before` | union \| null  | The function/section name after a text hunk's `@@` header, as a `{text\|bytes}` union; `null` for a text hunk without a heading, a whole-file hunk, or an `untracked` inventory entry. |
-| `additions`      | int            | Number of added lines.                                                                                                                                                                 |
-| `deletions`      | int            | Number of removed lines.                                                                                                                                                               |
-| `lines`          | array          | `show --json` only. The structured body; `[]` for a whole-file hunk. See below.                                                                                                        |
+| `schema_version` | int | Envelope version; bumped on any incompatible change to the shape below. |
+| `hunks` | array | The hunks (empty array when there are no changes). |
+| `id` | string | Full canonical SHA-256 Hunk ID; empty for an `untracked` entry, which no command can address. Human output uses a unique prefix of at least seven characters. |
+| `id_stability` | string | `stable` or `conditional`. An untracked inventory entry reports `stable`, but its empty `id` remains unaddressable. |
+| `file` | union | Repository path of the changed file, as a byte-safe `{text\|bytes}` union (see below). |
+| `status` | string | One of `staged`, `unstaged`, `untracked`. |
+| `change_kind` | string | Git status letter: `A` added, `D` deleted, `M` modified, `T` typechange (`R`/`C` reserved and currently rejected). Always present. |
+| `a_mode` | string | null | 6-digit octal git mode on the pre-image side; `null` when that side does not exist. |
+| `b_mode` | string | null | 6-digit octal git mode on the post-image side; `null` when that side does not exist. |
+| `binary` | bool | Whether the change is binary. Always present. |
+| `header` | string | null | The bare `@@ -a,b +c,d @@` range for a text hunk; `null` for a whole-file hunk (binary, mode-only, type, or empty tracked file change) or an `untracked` inventory entry. |
+| `context_before` | union | null | The function/section name after a text hunk's `@@` header, as a `{text\|bytes}` union; `null` for a text hunk without a heading, a whole-file hunk, or an `untracked` inventory entry. |
+| `additions` | int | Number of added lines. |
+| `deletions` | int | Number of removed lines. |
+| `lines` | array | `show --json` only. The structured body; `[]` for a whole-file hunk. See below. |
 
 A `lines` entry is `{ "n", "op", "content", "no_newline"? }`:
 
-| Field        | Type   | Description                                                                                         |
+| Field | Type | Description |
 | ------------ | ------ | --------------------------------------------------------------------------------------------------- |
-| `n`          | int    | 1-based position within the hunk body — the index `-l` line selection uses. Counts every body line. |
-| `op`         | string | `" "` context, `"+"` addition, `"-"` deletion.                                                      |
-| `content`    | union  | The line text **without** its leading op character, as a `{text\|bytes}` union.                     |
-| `no_newline` | bool   | Present and `true` only when the line has no trailing newline; consumes no `n`.                     |
+| `n` | int | 1-based position within the hunk body — the index `-l` line selection uses. Counts every body line. |
+| `op` | string | `" "` context, `"+"` addition, `"-"` deletion. |
+| `content` | union | The line text **without** its leading op character, as a `{text\|bytes}` union. |
+| `no_newline` | bool | Present and `true` only when the line has no trailing newline; consumes no `n`. |
 
 Any field carrying arbitrary git/source bytes (`file`, `context_before`,
 `lines[].content`) is a byte-safe `{text | bytes}` union: `{"text": "..."}` for
@@ -311,14 +322,6 @@ Adding a new field is backward-compatible and does not change `schema_version`;
 renaming, removing, or changing the type of an existing field bumps it. (Before
 `schema_version` existed, `list --json` returned a bare array.)
 
-## Comparison
-
-|                  | Interactive | Programmatic | Hunk IDs | Line-level control | JSON output |
-| ---------------- | ----------- | ------------ | -------- | ------------------ | ----------- |
-| `git add -p`     | Yes         | No           | No       | Yes                | No          |
-| `git add <file>` | No          | Yes          | No       | No                 | No          |
-| **`git-hunk`**   | **No**      | **Yes**      | **Yes**  | **Yes**            | **Yes**     |
-
 ## How it works
 
 1. Rejects detected rename, copy, and unmerged states.

{git_hunk-0.3.0 → git_hunk-0.4.0}/git_hunk/__init__.py

@@ -1,3 +1,5 @@
 import importlib.metadata
 
+__all__ = ["__version__"]
+
 __version__ = importlib.metadata.version("git-hunk")