Design 03: partial commits (commit <paths>, commit -p) and hooks

Read with design__00__index-and-reconciliation.md: where the two disagree (shared foundations F1–F9, the in-progress rules), the index wins.

Roadmap items: 2.3 (commit some files, not all) and 2.9 (hooks), from roadmap__git-parity.md (same folder). Status: design, not implemented. Written against 3a1d72a on claude/charming-babbage-5hzcxq (code identical to dev). Git reference: git 2.43.0. Every Git behaviour quoted below was run against that binary in a scratch repository on 28 Oct, unless marked "(docs)". Extension rule: nothing changes for a user who does not use these features. sgit commit with no paths still commits the whole working copy. A clone with no hooks folder runs nothing. No vault format change; no min_client gate.

1. Summary and the exact Git behaviour matched

1.1 sgit commit <pathspec>… (whole-file partial commits)

Git's git commit <pathspec> is git commit --only <pathspec>. It takes HEAD's tree, replaces the matched tracked paths with their working-tree content (or removes them if deleted), and commits only that. Everything else stays uncommitted, untouched on disk. Measured on git 2.43:

1.2 sgit commit -p (hunk selection)

Git has no commit -p of its own name for this; git commit -p runs git add -p on a temporary index and commits the result. The interactive keys of git 2.43 add -p: y n q a d j J g / e s p ? (also k K): yes / no / quit / all remaining in file / none remaining in file / leave undecided and go next / previous / go to / search / edit hunk / split hunk / print. sgit matches y n q a d s ? plus j k navigation. e (edit the hunk in an editor) is a non-goal for the first cut (decision D4). The working-tree file is never modified; only the committed blob is the partial content.

1.3 Hooks

Git runs executables named after the event from $GIT_DIR/hooks/ (or core.hooksPath). Measured and from githooks(5):

Further Git facts the design copies:

• The hook runs with its cwd at the root of the working tree, even when the command ran in a sub-folder (measured: cwd was the repo root for a commit made from d/).
• Git exports what child Git commands need (GIT_INDEX_FILE for pre-commit: measured; GIT_DIR is only set when it had to be found by other means; measured empty in a plain repo).
• A hook file that exists but is not executable is ignored with a hint (advice.ignoredHook) (docs).
• core.hooksPath replaces the hooks folder; it may be relative to the working-tree root (docs). Git never takes hooks from the repository content; a team that wants shared hooks points core.hooksPath at a tracked folder by hand (Husky and similar do this).
• git commit -n is --no-verify.

2. Scope and non-goals

In scope

1. sgit commit [-m MSG] [--] <pathspec>…, with folders, globs, deletions, new files, --amend, --json.
2. sgit commit -p [<pathspec>…] interactive, and a non-interactive hunk selection for agents (--list-hunks, --hunk ID).
3. Hooks: pre-commit, prepare-commit-msg, commit-msg, post-commit, pre-push, post-merge, post-checkout; --no-verify / -n; a per-clone hooks path (core.hooksPath equivalent).
4. Prerequisite: sgit push stops refusing a dirty working copy (5.4). Without it, a partial commit cannot be pushed, which defeats the feature.
5. sgit vault hooks to show the hooks path and what is installed (decision D6 on the name).

Non-goals (first cut)

• A persistent staging area (sgit add, restore --staged). Analysed in 5.6; decision D1.
• e (edit hunk) in -p; git add -p's regex search / and g goto.
• Pathspec magic (:(exclude), :!, :(icase), :(top), :(literal), :(glob)). Only literal paths, folders and the three wildcards * ? [...]. :!pattern is a cheap follow-up (decision D3).
• Hooks Git has beyond the seven above (pre-merge-commit, pre-rebase, post-rewrite, reference-transaction, pre-auto-gc, push-to-checkout, server hooks). post-rewrite (for --amend) is a one-line follow-up.
• Hooks for sgit write (plumbing; Git's plumbing runs no hooks either), except pre-push when write --push pushes (5.8).
• Hooks taken from vault content, synced, or set by the vault. Never.
• Template hooks copied into a fresh clone (Git's init.templateDir). A fresh sgit clone has no hooks.

3. CLI surface

3.1 sgit commit

sgit commit [MESSAGE] [-m MSG] [-d DIR] [--allow-deletions] [--allow-secret-file PATH]…
            [--amend] [-p | --patch] [--hunk ID]… [--list-hunks] [-n | --no-verify] [--json]
            [-- PATHSPEC…]

Disambiguating the positional message. Today sgit commit "msg" takes the first positional as the message (sgit_ai/cli/CLI__Main.py:375). Git takes positionals as pathspecs. The rule, chosen so that every existing invocation keeps its meaning:

argparse implementation: commit_parser.add_argument('args', nargs='*') replaces the message positional; CLI__Vault.cmd_commit splits it: with -m, all of args are pathspecs; without -m, the part before a literal -- must be at most one item (the message) and everything after -- is a pathspec. argparse drops a bare -- from the list, so the split point comes from the raw argv (implementation note at the end of section 10).

Flags added

Output (text), unchanged for the whole-copy commit. For a path commit:

Committed 2 file(s) to clone-abc… (2 of 7 changed; 5 left uncommitted).
  Commit: obj-cas-imm-…
  Left uncommitted: notes.md, src/x.py, … (sgit status)

Exit codes

3.2 sgit push, pull, branch switch, branch checkout, checkout, branch merge

One flag is added where Git has one: sgit push -n / --no-verify (skips pre-push). Pull, switch, checkout and merge only gain the post-hooks, which --no-verify does not affect in Git either. sgit write --push gains --no-verify for its push.

3.3 JSON shapes

sgit commit --json (success):

{"status": "committed", "commit_id": "obj-cas-imm-…", "branch_id": "clone-…", "message": "…",
 "files_changed": 2, "paths": ["a.txt", "b/c.md"], "left_uncommitted": ["notes.md"],
 "hunks": {"src/app.py": ["h-3f9a2c41d07b", "h-91aa…"]},
 "hooks": {"pre-commit": 0, "prepare-commit-msg": null, "commit-msg": 0, "post-commit": 0}}

hooks values: exit code, or null when not installed / not run. status is nothing_to_commit with no commit_id when that applies. Refusals print {"status": "refused", "reason": "…", "paths": […]} and exit 1.

sgit commit --list-hunks --json:

{"base_commit": "obj-cas-imm-…",
 "files": [
   {"path": "src/app.py", "binary": false, "status": "modified",
    "base_hash": "…", "work_hash": "…",
    "hunks": [
      {"id": "h-3f9a2c41d07b", "index": 1, "header": "@@ -10,6 +10,8 @@ def main():",
       "old_start": 10, "old_lines": 6, "new_start": 10, "new_lines": 8,
       "added": 2, "removed": 0, "text": " ctx\n+new line\n…",
       "splittable": true}
    ]},
   {"path": "logo.png", "binary": true, "status": "modified", "hunks": [{"id": "h-whole-…", "index": 1, "whole_file": true}]}
 ]}

Hunk ids are content-derived, never positional, so an agent's selection cannot land on the wrong hunk if the file changed between listing and committing: id = "h-" + sha256(path NUL base_hash NUL old_start NUL old_lines NUL removed lines NUL added lines)[:12]. Split sub-hunks get their own ids, listed with --list-hunks --split (each splittable hunk is replaced by its parts). --hunk refuses (exit 2) any id that is not in the freshly computed list, naming it, so a stale id fails loudly. New files list as one whole-file hunk; deletions as one whole-file "delete" hunk.

3.4 sgit vault hooks

sgit vault hooks                 # where hooks are read from, and each known hook: installed / executable / missing
sgit vault hooks --path DIR      # set the hooks path for this clone (core.hooksPath); relative = to the vault root
sgit vault hooks --unset         # back to .sg_vault/local/hooks
sgit vault hooks --json

Rule 9: hooks are per-clone configuration, not a daily verb, so they live under vault, not at the top level; TOP_LEVEL_COMMANDS does not change. (Git: git config core.hooksPath. sgit has no config command; decision D6.)

4. How the code works today

4.1 Commit

4.2 Trees

4.3 Scan and scan cache (sgit's half of Git's index)

4.4 Push, pull, switch, checkout (where hooks would fire)

4.5 Paths, the CLI root, secrets in the environment

5. Design

5.1 Pathspec semantics

New class Vault__Pathspec in sgit_ai/core/actions/commit/Vault__Pathspec.py:

class Vault__Pathspec(Type_Safe):
    patterns : list[Safe_Str__Pathspec]        # as typed, normalised to '/' separators
    prefix   : Safe_Str__Pathspec = None        # cwd relative to the vault root ('' at the root)

    def from_args(self, args: list, cwd: str, root: str) -> 'Vault__Pathspec'
    def is_glob(self, pattern: str) -> bool             # contains * ? or [
    def matches(self, path: str) -> bool                # any pattern
    def match(self, head_paths, disk_paths) -> tuple    # (matched: set, unmatched_patterns: list)

New safe type Safe_Str__Pathspec (sgit_ai/safe_types/Safe_Str__Pathspec.py): max_length 4096, regex rejects only control characters [\x00-\x1f\x7f] (paths may be any Unicode; Safe_Str__File_Path would rewrite * ? [ to _, see sgit_ai/safe_types/Safe_Str__File_Path.py:4). trim_whitespace = False (a file name may end in a space).

Rules (each one a test):

match(head_paths, disk_paths) takes the union of HEAD's flat paths and the scan's paths, so a deleted tracked file (in HEAD, not on disk) matches and becomes a deletion.

5.2 Building the commit tree from HEAD plus the selected paths

New method Vault__Sync__Commit._commit_selected(directory, c, old_flat, old_tree_ids, opaque, selected: dict), where selected is {path: bytes | None} (None = delete). It is the same shape as write_file's core, so the two share it:

1. flat = dict(old_flat). For each path, data in selected: None → flat.pop(path); bytes → encrypt_or_reuse_blob(data, old_flat.get(path), read_key) (Vault__Sub_Tree.py:517), entry {blob_id, size, content_hash, content_type, large} as write_file does (Vault__Sync__Commit.py:310-314).
2. Root tree: sub_tree.build_from_flat(flat, read_key, opaque=opaque, old_tree_ids=old_tree_ids, file_unchanged=lambda p: p not in selected).
3. Change to Vault__Sub_Tree.build_from_flat (Vault__Sub_Tree.py:105): add the parameters old_tree_ids: dict = None and file_unchanged: callable = None and pass them, with old_flat_entries=flat, to _build_tree_from_dir_contents (:556), which already implements the reuse. Today build_from_flat rebuilds every folder; with the reuse a pathspec commit (and sgit write, and every merge) builds only the folders on the selected paths' spines. Callers that pass nothing behave exactly as today (both default to None). Correctness: a folder is reused only if its names and every file in it are unchanged and its old tree is in the store (:593-604), and tree ids are content addresses, so a reused id is byte-identical to a rebuilt one. The test test_build_from_flat__reuse_gives_the_full_build_ids builds both ways and compares every id.
4. Same signing, same create_commit call, same ref write as commit() (Vault__Sync__Commit.py:162-188).

commit() gains the parameters paths: list = None, hunks: list = None, patch: bool = False, no_verify: bool = False, hooks: Vault__Hooks = None (5.5). When paths and hunks are both empty and patch is false, the existing code path runs unchanged (the only edit to it is the hook calls).

Selected-path flow (new private method _commit_paths):

1. Refusals first, before any read: merge in progress → Vault__Partial_Commit_Error('cannot do a partial commit during a merge') (new error class in sgit_ai/core/Vault__Errors.py).
2. HEAD's flat map as today (:69-78).
3. Scan only what the pathspec can reach:

• literal file paths: one lstat + the scan-cache rule per path (new Vault__Sync__Base._scan_paths(directory, rel_paths), extracted from the per-file body of _scan_local_directory :569-609 so both share one implementation: links skipped and kept, unreadable refused, FIFOs kept);
• literal folders: _scan_local_directory restricted to that sub-tree (new parameter under: list = None, which starts os.walk at each folder instead of the root; the ignore rules still load from the root);
• any glob: the full scan (it is what commit does today; the scan cache makes it cheap).

1. Vault__Pathspec.match(head_paths, disk_paths) → matched paths; unmatched patterns → refuse.
2. Changed = matched paths whose disk hash differs from HEAD's, plus matched HEAD paths missing on disk (deletions). Sparse / selective clones: a HEAD path not on disk is a deletion only if it is in the checkout set (Vault__Checkout_Set, as Vault__Sync__Commit.py:102-111), unless --allow-deletions.
3. Scoped clone: any changed path outside the scope → the existing refusal (:88-95), naming only the matched ones.
4. Secret guard on the changed paths (Vault__Secret_Guard.refuse_files, as :85-86).
5. Read the content of each changed path with Vault__Path_Guard.read_regular (O_NOFOLLOW).
6. _commit_selected(...), then the commit as above. Nothing on disk is written; the scan cache needs no update (it describes the working copy, which did not change).
7. Result dict adds paths (sorted committed paths) and left_uncommitted (changed paths not selected, from the scan when one was done, else omitted).

--amend with paths: base flat map = HEAD's tree (the commit being replaced), parents = HEAD's parents, exactly _amend_plan (:205-229), with the selected paths overlaid. Git does the same (git commit --amend <paths>).

5.3 Hunk selection (-p, --hunk, --list-hunks)

As implemented (28 Oct): the changes come from the shared differ Vault__Line_Diff (Myers with Git's change compaction, design__00 F1), not difflib, so hunk edges are where git diff puts them; hunks are grouped as xdiff does (≤ 2 × context equal lines between two changes share a hunk). Files up to 8 MiB (the line merge's cap). Schemas live in sgit_ai/schemas/commit/; a hunk carries its change blocks as list[Schema__Line_Hunk] and its body as one text string. --hunk accepts ids from both the plain and the --split listing. Prompt keys y n a d s j k q ?; end of input chooses nothing.

New class Vault__Hunks in sgit_ai/core/actions/commit/Vault__Hunks.py (pure: bytes in, bytes and schemas out):

class Vault__Hunks(Type_Safe):
    context : Safe_UInt__Hunk_Context = 3      # lines of context, Git's default (-U3)
    max_bytes : Safe_UInt__File_Size = 10 * 1024 * 1024   # above this a file is whole-file only

    def hunks_of(self, path: str, base: bytes, work: bytes) -> Schema__File_Hunks
    def split(self, hunk: Schema__Hunk) -> list           # [Schema__Hunk], 1 element when not splittable
    def apply(self, base: bytes, work: bytes, chosen: list) -> bytes   # chosen: [Schema__Hunk]
    def hunk_id(self, path: str, base_hash: str, hunk) -> str

New schemas (sgit_ai/schemas/commit/):

New safe types: Safe_Str__Hunk_Id (^h-[0-9a-f]{12}$), Safe_Str__Diff_Line (any text, no length cap below the file cap; \r kept), Safe_Str__Diff_Header, Safe_UInt__Hunk_Context, Enum__Hunk_File_Status. Every schema passes the round-trip invariant.

Algorithm

1. Lines: base.splitlines(keepends=True) and work.splitlines(keepends=True) on bytes, so CRLF and a missing final newline survive exactly. Text decoding only for display (errors='replace').
2. Binary (a NUL in the first 8 KB, the rule of Vault__Diff._is_binary, sgit_ai/core/actions/diff/Vault__Diff.py:534) or larger than max_bytes: one whole_file hunk.
3. difflib.SequenceMatcher(None, a, b, autojunk=False).get_grouped_opcodes(context) gives Git-shaped hunks (autojunk=False, else long files with repeated lines get worse diffs than Git's). Each group is one hunk; old_start / new_start are 1-based as in a unified header. Header text: @@ -s,l +s,l @@ plus, for text files, the nearest preceding line matching ^[A-Za-z_$] (a cheap stand-in for Git's funcname; display only).
4. Split (Git's s): a hunk whose group has more than one non-equal opcode separated by equal runs splits at each such run; each part keeps up to context lines on each side. A hunk with a single change block is not splittable (splittable = false), as in Git.
5. Apply: walk base lines; for each opcode of the full diff, emit the work side if its hunk (or sub-hunk) was chosen, else the base side. Unchosen insert emits nothing, unchosen delete keeps the base lines. Since every chosen block is an opcode of the same SequenceMatcher run, blocks never overlap and the result is well defined. Property tests: choose all → work; choose none → base; any subset → git apply --cached of the same hunks gives the same bytes (Git as oracle, 9.2).
6. New file: one hunk (all added). Choosing it adds the file; not choosing leaves it out. Deleted file: one hunk; choosing it deletes. Git's add -p behaves the same for intent-to-add / deleted files.
7. The partial content becomes a blob through _commit_selected (5.2) as {path: bytes}. The working copy is never written. The scan cache is not touched. After the commit sgit status shows the file as modified (the rest of the hunks), which is exactly Git's state after add -p + commit.

Base content. HEAD's blob for the path: obj_store.load(blob_id) + crypto.decrypt. On a sparse, scoped or pack-store clone the blob of a file that is on disk is local (it was written from it); if not, fetch it with the existing blob fetcher (Vault__Sync__Base._make_blob_fetcher, Vault__Sync__Base.py:81) and verify by content address as every fetch does. Read-only clones refuse commit already.

Interactive prompt — new class CLI__Hunk_Prompt (sgit_ai/cli/CLI__Hunk_Prompt.py), using input():

diff --sgit a/src/app.py b/src/app.py
@@ -10,6 +10,8 @@ def main():
 …
(1/3) Commit this hunk [y,n,q,a,d,s,j,k,?]?

Colour only when stdout is a TTY and NO_COLOR is unset. Ctrl-C aborts with nothing committed (exit 130, as CLI__Main.py:1062 does today).

Non-interactive: --list-hunks [--split] [--json] prints; --hunk ID… selects. Both compute the hunks the same way from the same inputs, so the ids agree as long as the file and HEAD did not change; if either changed the id is gone and --hunk exits 2 naming it.

5.4 Prerequisite: push with a dirty working copy

Vault__Sync__Push.push refuses any uncommitted change (Vault__Sync__Push.py:92-96). After a partial commit there are uncommitted changes by definition, so push would always refuse. Git pushes with a dirty tree.

Change: drop the clean refusal. Keep:

• the conflict-file refusal (_check_no_conflict_files, :48, :1059) and the merge-in-progress refusal (:49);
• push's implicit pull (:177-183), which already runs the dirty-tree guard (Vault__Pull__Guard): a dirty file the incoming merge does not touch is carried over, one it would touch refuses the pull and therefore the push before anything is written, naming the file ("commit them or sgit vault stash, then pull again").

The status call (:93) stays only to print a one-line note: note: 5 uncommitted change(s) stay local (not pushed). push --force skips the pull (:178) and so never touches the working copy: unchanged.

Test: test_push__dirty_tree_not_touched_by_incoming_is_pushed and test_push__dirty_file_the_pull_would_change_refuses (two clones on the in-memory API).

5.5 Hooks runner

New package sgit_ai/core/hooks/ with:

class Enum__Hook_Name(Enum):                     # sgit_ai/safe_types/Enum__Hook_Name.py
    PRE_COMMIT = 'pre-commit'; PREPARE_COMMIT_MSG = 'prepare-commit-msg'; COMMIT_MSG = 'commit-msg'
    POST_COMMIT = 'post-commit'; PRE_PUSH = 'pre-push'; POST_MERGE = 'post-merge'; POST_CHECKOUT = 'post-checkout'

class Schema__Hook_Result(Type_Safe):            # sgit_ai/schemas/hooks/Schema__Hook_Result.py
    hook        : Enum__Hook_Name = None
    ran         : bool            = False
    exit_code   : Safe_Int        = 0
    duration_ms : Safe_UInt
    path        : Safe_Str__File_Path = None     # the file run (display only)

class Vault__Hooks(Type_Safe):                   # sgit_ai/core/hooks/Vault__Hooks.py
    disabled : bool = False                      # --no-verify sets the verify hooks off (see VERIFY_HOOKS)
    timeout  : Safe_UInt__Hook_Timeout = 0        # seconds; 0 = none (Git has none)

    def hooks_dir(self, directory: str) -> str
    def find(self, directory: str, hook: Enum__Hook_Name) -> str            # path or ''
    def run(self, directory: str, hook: Enum__Hook_Name, args: list = None,
            stdin: bytes = b'', no_verify: bool = False) -> Schema__Hook_Result
    def environment(self, directory: str, hook: Enum__Hook_Name) -> dict
    def message_file(self, directory: str) -> str                           # .sg_vault/local/COMMIT_EDITMSG

class Vault__Hook_Error(Exception)                # sgit_ai/core/Vault__Errors.py: "<hook> hook failed (exit N): <what was not done>"

VERIFY_HOOKS = {PRE_COMMIT, COMMIT_MSG, PRE_PUSH}: the ones --no-verify skips (Git's scope, measured for prepare-commit-msg).

Discovery (hooks_dir, find):

1. hooks_path from the local config (new field, below); else <root>/.sg_vault/local/hooks/. A relative hooks_path is relative to the vault root (Git's rule for core.hooksPath).
2. Refused hooks paths (5.6, decision D5): a hooks_path that resolves inside the working tree is refused at run time unless hooks_path_tracked is also set (sgit vault hooks --path DIR --allow-tracked), because then the hooks are vault content that any teammate's push rewrites.
3. The hook file is <dir>/<name> exactly (POSIX). It must be a regular file (lstat; a symlink inside the hooks folder is allowed and resolved, since the folder is the user's own, not vault content) and executable (os.access(path, os.X_OK)). Present but not executable: skipped, with one stderr line per command: hint: the pre-commit hook was ignored because it is not executable (chmod +x .sg_vault/local/hooks/pre-commit).
4. Windows (no exec bit, no shebang exec): look for <name>.exe, <name>.cmd, <name>.bat, <name>.ps1, then <name> with a #! line. .ps1 runs as powershell -NoProfile -ExecutionPolicy Bypass -File <hook> args…; a #! script runs through sh if sh.exe is on PATH (Git for Windows puts it there), else it is skipped with a hint. Decision D7.

Execution (run):

• subprocess.run([hook_path, *args], cwd=<vault root>, env=self.environment(...), input=stdin, timeout=timeout or None, check=False). No shell. argv is a list; nothing is interpolated.
• stdout and stderr are inherited (the user sees the hook's output, as in Git), except under --json, where the hook's stdout is redirected to sgit's stderr so stdout stays one JSON object.
• cwd is the vault root even when sgit was run from a sub-folder (measured Git behaviour).
• ENOEXEC (no #! line) → exit code 126 recorded and reported as a failure with hook <name> could not be executed (no #! line?); FileNotFoundError on the interpreter → 127. Same codes as a shell.
• Timeout (only if configured): kill, exit code 124, reported as failure.
• Time is recorded in duration_ms (--json shows it).

Environment (environment): start from os.environ, then:

Never added: the vault key, read key, write key, access token, the server URL with a token. The hook runs as the same user and can read .sg_vault/local/vault_key itself; stripping is about not leaking secrets into processes and logs that did not ask for them (CI logs printing env, child tools that upload their environment), not a security boundary. The design says so in the threat-model row (6).

Messages: message_file is .sg_vault/local/COMMIT_EDITMSG, written with Vault__Storage.write_private (0600) before prepare-commit-msg, read back after commit-msg, left in place afterwards (Git leaves COMMIT_EDITMSG). It holds a plaintext commit message on local disk, the same class of data as the flat and scan caches (TM-R41).

Configuration (local only, never synced): two new fields in Schema__Local_Config (sgit_ai/schemas/Schema__Local_Config.py:22):

    hooks_path         : Safe_Str__File_Path       = None          # core.hooksPath: '' or None = .sg_vault/local/hooks
    hooks_path_tracked : bool                      = False         # the user accepted a hooks path inside the working tree

Older clients read a config with these keys fine (unknown keys are accepted by from_json, verified for Schema__Object_Commit; the same test is added for Schema__Local_Config); an older client that rewrites the config drops them, which only means hooks fall back to the default folder: fail-safe.

hooks_timeout is not a config field in the first cut; SGIT_HOOK_TIMEOUT (seconds) is read by Vault__Hooks for agents that need a bound (decision D8).

5.6 Where each hook fires

Why pre-commit runs before the scan. In Git the index is the commit; a formatter run by pre-commit changes the working tree, not the index, and a common complaint is that the fix is not in the commit. In sgit the working copy is the commit (no index), so running pre-commit first means a formatter's edits are committed, and a check sees exactly what will be committed. For commit <paths> and -p, the hunks are computed after pre-commit too.

sgit write runs no commit hooks (plumbing). sgit write --push runs pre-push (it is a push), skippable with write --no-verify. History edits (history undo, reset, revert --as-commit): in the first cut only commit (including --amend) runs the commit hooks. Git's git revert does run prepare-commit-msg and commit-msg; adding them to revert --as-commit is decision D9.

5.7 Staging area: analysis for decision D1

Git's index (.git/index) does three jobs:

So the only missing job is the second. Options:

Recommendation A now; B later as an extension if users ask, built on _commit_selected (5.2) so it adds no new tree code.

6. Security and threat model

--no-verify is a convenience, not a control: anyone who can run sgit commit can delete the hook. The design says so in the docs; teams that need enforcement need it server-side (SGitHub, roadmap section 4).

7. Interactions

8. Performance

Measured costs of today's commit on the 76,000-file synthetic vault (release-readiness note, 26 Oct): a 5-file commit plus push 4.5–5.2 s, of which the scan with a warm cache is most of the commit.

Perf tests (in tests/unit/perf/ if the folder exists, else alongside, marked slow-safe): a 20,000-file vault, one literal path commit must not call _scan_local_directory (asserted by a counter attribute on a subclass of Vault__Sync__Commit used only in the test, no mocks) and must build at most depth + 1 new trees (count objects in the store before/after).

9. Test plan

All real objects, no mocks; vaults from Vault__Test_Env (tests/_helpers/vault_test_env.py) or two clones on Vault__API__In_Memory; no __init__.py in test folders. Git is available in CI (/usr/bin/git); oracle tests skip with a reason if git is missing.

9.1 Pathspec and partial commits — tests/unit/core/actions/commit/test_Vault__Pathspec.py, test_Commit__Paths.py

9.2 Hunks — tests/unit/core/actions/commit/test_Vault__Hunks.py, test_Commit__Patch.py, tests/unit/cli/test_CLI__Hunk_Prompt.py

9.3 Push with a dirty tree — tests/unit/workflow/push/test_Push__Dirty_Tree.py

test_push__dirty_tree_not_touched_by_incoming_is_pushed, test_push__dirty_file_the_pull_would_change_refuses (store, refs and working copy unchanged), test_push__force_never_touches_working_copy, test_push__conflict_files_still_refuse, test_push__prints_uncommitted_note.

9.4 Hooks — tests/unit/core/hooks/test_Vault__Hooks.py, test_Hooks__Commit.py, test_Hooks__Push_Pull_Checkout.py

Hooks are real executable files (#!/bin/sh on POSIX; .cmd on Windows) written by the test into the hooks folder; each writes its argv, cwd, selected env vars and stdin to a file the test reads.

9.5 Schemas and CLI — existing patterns

Round-trip tests for Schema__Hunk, Schema__File_Hunks, Schema__Hunk_List, Schema__Hook_Result, the extended Schema__Local_Config (including reading a config with the new keys through an instance of the old schema: unknown keys accepted). TOP_LEVEL_COMMANDS unchanged (the test stays green without an edit). sgit help all lists nothing new at the top level.

9.6 Acceptance checklist (implementation and deployment)

• [ ] pytest tests/unit -n auto and pytest tests/security green; no __init__.py added under tests/.
• [ ] sgit commit, sgit commit "msg", sgit commit -m msg behave exactly as before (existing tests unchanged).
• [ ] sgit commit -m x a b/ commits only a and changes under b/; sgit status lists the rest.
• [ ] Unmatched pathspec exits 1 and writes nothing (object count and ref unchanged).
• [ ] Partial commit during a merge is refused with Git's message.
• [ ] sgit push succeeds with uncommitted edits the incoming merge does not touch, and refuses (nothing written) when it would.
• [ ] sgit commit --list-hunks --json then --hunk <id> commits exactly the listed text; the working file is unchanged.
• [ ] 64-subset Git oracle for hunk apply passes.
• [ ] sgit write produces the same tree ids as before, faster on a 20k-file vault (timing printed by the perf test).
• [ ] Each of the seven hooks fires at its call site with Git's arguments and stdin; --no-verify scope matches Git.
• [ ] No hook environment contains a key, token or SG_SEND_PASSPHRASE.
• [ ] A hooks path inside the working tree is refused without explicit opt-in.
• [ ] Threat-model rows added (6), Fixed__Hooks security test present.
• [ ] CHANGELOG [Unreleased] entries for both features, with the push behaviour change called out.
• [ ] README / sgit help commit show the new forms; sgit vault hooks documented.
• [ ] Dev pre-release published; on it, the newsroom-style flow (agent edits 5 files, commits 2 by path, pushes, a teammate pulls) run once on the live dev server.

10. Implementation steps (ordered commits)

Total about 7.5 days (2.3 ≈ 4.5 days with the push prerequisite and the tree reuse; 2.9 ≈ 3 days). The roadmap's "1 day / 2 days" for 2.3 did not include the push change, the shared build_from_flat reuse, the agent hunk interface or the Git oracle.

Parser note for step 3: declare commit_parser.add_argument('args', nargs='*'); argparse drops a bare -- from nargs='*' lists, so cmd_commit finds the split point by locating '--' in sys.argv after the commit token (the CLI receives argv through CLI__Main.run; pass the raw list down as args.raw_argv set in run for the commit command only), which keeps the rule testable without patching sys.argv.

11. Open decisions for Dinis

This page as markdown · its source, admin/content/research/git-parity-design-partial-commits.md