Design 05: sgit history bisect (roadmap item 2.6)

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

Status: design, not started. Roadmap: roadmap__git-parity.md, priority 2, item 2.6. Code read for this document: this repository at 3a1d72a (claude/charming-babbage-5hzcxq). Git used as the reference: git 2.43.0 (installed here). Every Git behaviour quoted below was either run here against a scratch repository or read from builtin/bisect.c / bisect.c; the run-here ones are marked (run).

1. Summary, and the exact Git behaviour matched

sgit history bisect finds the commit that introduced a change by binary search over the commit graph, like git bisect. The user (or a command, with run) marks commits good or bad; sgit writes each candidate commit into the working copy until one commit is left.

The one structural difference from Git is where "HEAD" is. Git detaches HEAD and leaves the branch alone. sgit has no separate HEAD: the clone branch's ref is the head. So bisect never moves any ref. It records the commit under test in a local state file and writes that commit's files into the working copy; status, cat, ls and checkout read that commit while a bisect is in progress. reset writes the clone head's files back. Because no ref moves, a lost or damaged state file can never lose a commit: the head was never touched.

Git behaviour matched

2. Scope and non-goals

In scope: start, bad/new, good/old, custom terms, skip (single revs and A..B ranges), next, reset, log, replay, view/visualize, run, terms, status (sgit extra: the state as text or JSON), --first-parent, --no-checkout, a pathspec, --json on every subcommand. Full, selective (sparse / no-checkout), scoped, shallow, read-only, pack and pack-store clones. The commands that must refuse or change behaviour while a bisect is in progress (7.1).

Not in scope:

• gitk. view prints a log; nothing graphical.
• Moving refs. Bisect never writes a ref, a baseline, the branch index or the reflog.
• Network writes of any kind (6.3 proves it).
• Fetching history behind a shallow boundary on its own. A shallow clone says so and stops (7.3).
• Committing during a bisect. Git allows commits on its detached HEAD, which bisect reset then orphans; sgit refuses them (decision D1).
• Changing branch checkout <commit>'s existing "detached" behaviour (CLI__Vault.py:1567, which writes every file of the commit with no state and no dirty check). It is a related hazard noted in 11 (D7), not fixed here.

3. CLI surface

Rule 9: bisect is about commits, so it goes under history. No top-level command is added.

3.1 Subcommands

Every subcommand takes --directory DIR (default .) and --json.

Custom terms. Git accepts git bisect fixed after --term-new fixed. argparse cannot add sub-parsers at run time, so bisect is one parser with subcommand (positional) and args (argparse.REMAINDER), and CLI__Bisect.dispatch maps the word: a built-in subcommand, good/bad/old/new, or the recorded term names. A term may not be a subcommand name (help start skip next reset visualize view replay log run terms status), and old and new may not be equal: Git's rule, enforced by Safe_Str__Bisect_Term plus a check in start (decision D2).

3.2 Output (text)

$ sgit history bisect start HEAD HEAD~15
Bisecting: 7 revisions left to test after this (roughly 3 steps)
[a1b2c3d4e5f6] c8 — the commit message's first line
  wrote 1 file, removed 0 (working copy is now at a1b2c3d4e5f6; your branch head is unchanged)

$ sgit history bisect good
Bisecting: 3 revisions left to test after this (roughly 2 steps)
[…] c12

$ sgit history bisect bad
…
obj-cas-imm-9f8e7d6c5b4a is the first bad commit
<history show output for it>
  (sgit history bisect reset   returns the working copy to your branch head)

Waiting states, as Git words them: status: waiting for both good and bad commits, status: waiting for good commit(s), bad commit known, status: waiting for bad commit, 1 good commit known.

status during a bisect gains a first line: Bisecting: working copy at <id> (<k> candidates left); branch head <id> unchanged. sgit history bisect reset to return.

3.3 Exit codes

3.4 --json shape

Every subcommand prints one JSON object (run prints one at the end; with --json it prints no per-step text):

{
  "status":      "bisecting",           // waiting | bisecting | found | only_skipped | merge_base_bad | reset
  "terms":       {"old": "good", "new": "bad"},
  "bad":         "obj-cas-imm-…",       // null while unknown
  "good":        ["obj-cas-imm-…"],
  "skipped":     [],
  "current":     "obj-cas-imm-…",       // the commit in the working copy; null with --no-checkout until marked
  "remaining":   7,                     // Git's "revisions left to test after this"
  "steps":       3,                     // Git's "roughly N steps"
  "candidates":  15,                    // size of the candidate set
  "first_bad":   null,                  // the id when status = found
  "possible":    [],                    // the ids when status = only_skipped
  "branch_head": "obj-cas-imm-…",       // never changes during a bisect
  "written":     1, "deleted": 0, "kept_dirty": [], "not_written": [],
  "paths":       [],                    // the pathspec
  "first_parent": false, "no_checkout": false
}

run --json adds "runs": [{"commit": "…", "exit_code": 0, "verdict": "good", "seconds": 0.4}].

4. How the code works today (file:line)

5. Design

5.1 State: .sg_vault/local/bisect.json

Written with Vault__Secret_File.write (crypto/Vault__Secret_File.py:14: temp file 0600, rename). It holds commit ids and paths, which .sg_vault/local/ already holds (reflog, flat cache), so 0600 is consistency, not secrecy.

New types:

Schemas (folder sgit_ai/schemas/bisect/, like schemas/merge/):

class Schema__Bisect_Log_Entry(Type_Safe):
    action    : Enum__Bisect_Log_Action  = None
    commit_id : Safe_Str__Commit_Id      = None
    args      : list[Safe_Str__Commit_Id]          # START: [bad, good...]; SKIP of a range: every id
    subject   : Safe_Str__Commit_Message = None    # first line, for the "# bad: [...] subject" comment

class Schema__Bisect_Transition(Type_Safe):         # a step in flight (crash recovery, 5.6.4)
    from_commit : Safe_Str__Commit_Id = None
    to_commit   : Safe_Str__Commit_Id = None

class Schema__Bisect_State(Type_Safe):
    schema_version  : Safe_UInt                      # 1
    branch_id       : Safe_Str__Branch_Id   = None   # the clone branch when the bisect started
    branch_head     : Safe_Str__Commit_Id   = None   # its head then; checked on every command (7.1)
    term_old        : Safe_Str__Bisect_Term = None   # 'good' unless --term-old
    term_new        : Safe_Str__Bisect_Term = None   # 'bad'  unless --term-new
    bad             : Safe_Str__Commit_Id   = None
    good            : list[Safe_Str__Commit_Id]
    skipped         : list[Safe_Str__Commit_Id]
    current         : Safe_Str__Commit_Id   = None   # the commit whose files the working copy holds
    paths           : list[Safe_Str__File_Path]       # the pathspec ([] = everything)
    first_parent    : bool                  = False
    no_checkout     : bool                  = False
    merge_bases_ok  : bool                  = False   # Git's BISECT_ANCESTORS_OK
    transition      : Schema__Bisect_Transition = None
    first_bad       : Safe_Str__Commit_Id   = None
    started_ms      : Safe_UInt__Timestamp
    log             : list[Schema__Bisect_Log_Entry]

Safe_Str__Commit_Message exists (safe_types/Safe_Str__Commit_Message.py); the subject is its first line.

Round-trip invariant (CLAUDE.md rule 6): Schema__Bisect_State.from_json(s.json()).json() == s.json().

5.2 Classes and responsibilities

All new code under sgit_ai/core/actions/bisect/ (with an empty __init__.py, as every action package has).

Plus Schema__Bisect_Run(Type_Safe): exit_code : Safe_Int, seconds : Safe_Float, timed_out : bool, verdict : Enum__Bisect_Verdict = None, aborted : bool.

Errors (sgit_ai/core/Vault__Errors.py): Vault__Bisect_Error(Exception) for refusals by bisect itself and Vault__Bisect_In_Progress_Error(Exception) for other commands refused during a bisect. Both are added to the "refused on purpose" tuple in CLI__Main._print_friendly_error (cli/CLI__Main.py:1203-1213), so the user sees error: <message> and no traceback.

5.3 The candidate set

Input: bad, goods (≥ 1), skipped, paths, first_parent.

1. Painting walk (Vault__Bisect__Graph.candidates). A max-heap of (generation, commit_id) starts with bad (flag NEW) and every good (flag OLD). Pop the highest generation; merge flags if seen; push its parents (only the first with first_parent) carrying the flag. Stop when every entry left in the heap is OLD (the paint_down_to_common rule: nothing below can be NEW-only). Candidates = commits painted NEW and not OLD. Generations come from Vault__Pack_Index.generation_of (Vault__Pack_Index.py:137), memoised in local/index/generations.json. On a loose vault the memo is built on first use (one decrypt per commit, once per clone). A commit not in the store (a shallow boundary's parent) has generation 0 and no parents. Unbounded: no limit=200 (unlike find_lca, Vault__Fetch.py:78).
2. Pathspec (when paths is non-empty, or by default on a scoped clone, 7.3). A candidate is kept when touches_paths is true:

• for each path, resolve the entry id (tree id or blob id) at that path in the commit's root tree and in each parent's, walking only the spine (one tree read per path segment, Vault__Sub_Tree._entries_by_name, Vault__Sub_Tree.py:306);
• a non-merge commit touches when any id differs from its parent's;
• a merge touches when, for some path, its id differs from every parent's (the merge itself changed it). Commits not kept stay in the graph for reachability (weights count only kept commits reachable through them). This approximates Git's history simplification, which also prunes merge parents; it is equal to Git on linear histories (tested, 9.3) and documented as an approximation for merges (decision D4).

1. Skipped commits stay candidates for counting (as in Git) and are excluded only when choosing.
2. Ancestry check before the first step (merge_bases_ok false): for each good g, if is_ancestor(g, bad) is false (Vault__Ref_Guard.is_ancestor, :23), compute merge_bases(g, bad) (all of them, by painting).

• A merge base not yet marked: it is the next commit to test, with the line Bisecting: a merge base must be tested.
• A merge base marked bad: stop with Enum__Bisect_Status.MERGE_BASE_BAD and Git's message, plus a hint: if you are looking for the commit that FIXED something: sgit history bisect start --term-old broken --term-new fixed.
• A merge base marked skipped: print Git's warning (… we cannot be sure the first bad commit is between <mb> and <bad>. We continue anyway.) and continue.
• All good: set merge_bases_ok = True, then continue normally.

5.4 The midpoint

n = len(candidates). For each candidate c, w(c) = number of candidates reachable from c through the graph (c included). Computation: process candidates in increasing generation; reach(c) = {c} ∪ ⋃ reach(p) over parents restricted to the candidate subgraph. A bitset per commit (Python int used as a bitset, candidates indexed 0..n−1) keeps this exact for DAGs at n · n / 8 bytes: 10,000 candidates is 12.5 MB, acceptable. For n > 50,000, use Git's approach: exact counts for single-parent chains (w = w(parent) + 1) and a bitset only below merges. Linear histories are always O(n).

Choice (best):

• score(c) = min(w(c), n − w(c));
• skip commits in skipped;
• choose the highest score; ties go to the smaller w, then the lower generation, then the smaller id.

That tie rule reproduces Git on every vector run here (9.3): 15 linear → c8 (w = 7, not c9 with w = 8); first-parent 5 → m3; the merge graph → b3. Git's own tie order depends on its counting order and, under skip, on SHA-1 order, so for DAGs with ties the tests assert this documented rule, not Git's pick.

Progress numbers: remaining = n − w(chosen) − 1, steps = estimate_steps(n); for 15 → 7, 3.

Termination:

• n == 1 (only bad left): first_bad = bad, status FOUND.
• Every candidate but bad is skipped: status ONLY_SKIPPED, possible = skipped candidates plus bad, sorted by generation descending (Git prints them that way).
• Shallow clone and first_bad is a boundary commit (Vault__Scope.is_boundary): print <id> is the first bad commit this clone can see: its parents are behind the shallow boundary (sgit fetch --unshallow, then sgit history bisect replay <log>); status FOUND, "at_boundary": true in JSON.

5.5 Skip (skip_away, ported from Git)

When the best candidate is skipped:

1. Sort the non-skipped candidates by score descending, ties by w ascending, then id (Git sorts by distance then oid).
2. count = len(sorted), prn = ((count * 1103515245 + 12345) & 0xFFFFFFFF) // 65536 % 32768, index = (count * prn // 32768) * isqrt(prn) // isqrt(32768).
3. Choose sorted[index]; if that is bad, choose the entry before it, or sorted[0].

Vectors (count → index): 14 → 0, 13 → 6, 12 → 0, 7 → 3, 6 → 0 (computed with this formula; with Git on the 16-commit history, skipping c8 gave c9 (index 0) (run)).

skip A..B marks every commit in ancestors(B) − ancestors(A), as Git does.

5.6 Moving the working copy between steps

Vault__Bisect__Working_Copy.move(directory, from_id, to_id, state):

1. Diff. diff_trees(tree(to), tree(from)) (Vault__Sub_Tree.py:259): only differing folders are opened. On a scoped clone, flatten both with Vault__Scoped_Tree.flatten (in-scope only) and diff the two maps. Result: writes (added and modified in to), deletes (in from, not in to).
2. Guard (before any write). The pull guard, with "ours" = flat(from) and "merged" = flat(to):

• scan = _scan_local_directory(directory, verify=touched);
• dirty = Vault__Pull__Guard().dirty_paths(directory, ours, scan, obj_store=…, sparse=…, checkout=…);
• plan = guard.plan(dirty, ours, merged, scan, blob_hash_fn=…);
• blocked = plan['blocked'] + guard.blocked_targets(directory, writes, deletes).
• A blocked path refuses the step with Vault__Dirty_Working_Tree_Error(guard.message(blocked)), nothing written: Git's "Your local changes to the following files would be overwritten by checkout".
• Dirty files the move does not touch are carried over (Git behaves the same). Flattening from and to in full is avoided: the guard only needs the entries for touched paths, which the diff already returned, plus scan.

1. Selective clones. Pull__Selective().setup(directory, obj_store, local_config, no_checkout=False); to_write, skipped = selective.split(writes). Paths not checked out stay not checked out and are reported as not_written. After writing, selective.after_write(written, deletes, stale=selective.stale_of(skipped, ours)) keeps the checkout record right (Pull__Selective.py:59).
2. Missing blobs (a loose sparse clone): batch-read through api.batch_read, verified before they are saved, exactly as Vault__Sync__Checkout._download (Vault__Sync__Checkout.py:160). This is a read; see 6.3.
3. Write. _remove_deleted_flat for deletes, then _checkout_flat_map(directory, to_write, …, failed=failed) (Vault__Sync__Base.py:674), which also seeds the scan cache. Any failed entry raises after the state records current = to_id (the files that were written are to's), with the paths and reasons; status shows them as modified, and next or reset retries.

5.6.1 Write order and crash recovery

1. Write the state with transition = {from, to}.
2. Apply the move.
3. Write the state with current = to, transition = None.

If a process dies between 1 and 3, the next bisect command sees transition and re-applies the move from from to to. Files already written equal to's versions, and the guard's plan treats bytes equal to the incoming version as current (Vault__Pull__Guard.plan), so the retry writes only what is left. reset does the same before returning to the head.

5.6.2 --no-checkout

Like Git's --no-checkout (which keeps BISECT_HEAD instead of moving HEAD): nothing is written; current moves and is shown. The run command gets SGIT_BISECT_COMMIT (5.8). During the bisect, sgit cat <path> and sgit ls read the commit under test (5.9), so a script can do sgit cat src/app.py | … with no checkout. This is the agent-friendly mode and the cheapest on a 76,000-file vault.

5.7 reset

1. If a transition is recorded, finish it (5.6.1).
2. Move the working copy from current back to the clone head (5.6), with the same guard: dirty files that the move would overwrite refuse the reset, naming them (--force overwrites, as git bisect reset does not need; we keep the guard by default because sgit has no index to protect them). Not touching the head's other files means a bisect on a 76,000-file vault resets in the time of its last diff.
3. Delete bisect.json.
4. reset <commit> (Git: "go to this commit instead of the original branch"): after 1–3, Vault__Sync__Pull.reset (directory, commit) (Vault__Sync__Pull.py:24), the existing history reset, which moves the clone ref and writes the reflog. That is the only path in this design that moves a ref, and it is an explicit user request.
5. If bisect.json is unreadable, current is unknown, and reset cannot tell the user's edits from files the bisect wrote. It compares the disk with the clone head's flat (_scan_local_directory against flatten(head)), refuses, and lists the paths that differ; --force writes the head's version of each. Commits are never at risk: no ref moved.

If the clone head moved during the bisect (it cannot through sgit, 7.1, but a second process or a manual ref edit could), reset still returns to the current head and says your branch head moved during the bisect (from X to Y).

5.8 run

Loop:

if status is WAITING:      refuse: "bisect run needs a good and a bad commit first"
first = True
while status == BISECTING:
    r = Runner.run(argv, cwd=directory, env=env(current), timeout, shell)
    if r.aborted (exit < 0 or >= 128, or timeout):   print Git's message; exit with that code (state kept)
    code = r.exit_code
    if first and code in (126, 127):
        # Git's check: is the command itself broken? run it once on a good commit
        move working copy to good[0]; r2 = run(...); move back to current
        if r2.exit_code == code: error "bogus exit code {code} for good revision"; exit 1
    first = False
    verdict = GOOD if code == 0 else SKIP if code == 125 else BAD
    mark(verdict, [current])                         # prints the next "Bisecting: …" or the result
return 0 if FOUND, 2 if ONLY_SKIPPED, 1 if MERGE_BASE_BAD

Vault__Bisect__Runner.run:

• argv, never a shell string. subprocess.run([str(a) for a in argv], cwd=directory, env=env, timeout=timeout, stdin=subprocess.DEVNULL), output passed through to the terminal (not captured), as Git does. A missing binary is 127 (the Container__Command_Runner rule, :21).
• --shell (sgit extra, explicit): ['/bin/sh', '-c', ' '.join(argv)] on POSIX, ['cmd', '/c', …] on Windows. Git always runs through the shell; sgit makes the shell opt-in so a path or a vault file name in the arguments is never interpreted (decision D3).
• env: a copy of os.environ plus SGIT_BISECT_COMMIT=<current>, SGIT_BISECT_BAD=<bad>, SGIT_BISECT_STEP=<n>, SGIT_BISECT_TERM_OLD, SGIT_BISECT_TERM_NEW. Never the vault key, read key, write key or token: those are not added, and the variables sgit itself reads for secrets are not set by bisect.
• cwd: the vault directory (the working copy root), as Git runs in the worktree.
• timeout (sgit extra): --timeout SECONDS; a timeout kills the process group and counts as an abort (exit 124 printed, run exits 124). Decision D5 offers "count it as skip" instead.
• Ctrl-C: KeyboardInterrupt stops the loop, state kept, exit 130.
• Each run prints running <argv joined with shlex.join>.

5.9 The "working commit" hook (what other commands read during a bisect)

One method, Vault__Bisect__State.working_commit(directory) -> str, returns current during a bisect and '' otherwise. Three places use it:

history log, history diff and history show keep reading the clone head and explicit revisions; view is the bisect-specific log. (Git's git log during a bisect starts from the detached HEAD. sgit users get the same through history log <current>; decision D6.)

5.10 File-by-file changes

New files:

Changed files:

The check_not_in_progress message: Cannot <action>: a bisect is in progress (working copy at <current>; your branch head <head> is unchanged). sgit history bisect reset ends it.

5.11 Compatibility

• No format change, no gate. Nothing is written to the vault or the host. Old clients, the web UI and other clones see nothing.
• An older sgit run inside a folder with a bisect in progress does not know bisect.json: its status would show the bisect commit's files as modifications and its commit would commit them. The guard against that is the user's, as with any local tool mix; sgit update is the remedy. Noted in the CHANGELOG entry.
• The local/index/generations.json memo is created on loose vaults too. It is a derived cache that Vault__Pack_Index already treats as such.

6. Security and threat model

6.1 Running user commands (run)

6.2 State tampering

bisect.json is local. Whoever can write it can already write the working copy and the refs. What a damaged or edited state can and cannot do:

• It cannot move a ref, push or delete a commit: bisect has no code path that writes a ref (except reset <commit>, an explicit user request through the existing history reset).
• Ids in it are re-validated on read (Safe_Str__Commit_Id) and must exist in the store; an unknown id refuses with bisect state names a commit this clone does not have: sgit history bisect reset.
• Paths in it (paths) are used only for matching, never joined to the disk path without Vault__Path_Guard.safe_join.
• A replay log (replay <file>) is untrusted text. Vault__Bisect__Log.parse accepts only lines matching ^(sgit history bisect|git bisect) (start|good|bad|old|new|skip|terms|<term>)( .*)?$ and # comments; every id is resolved through Vault__Revision.resolve (local only). Nothing in the file is executed; run lines are refused with a message.

6.3 No network writes during a bisect (proof)

• By construction. The only network calls in the bisect code are api.batch_read and api.read_large, for blobs a loose sparse clone lacks (5.6, step 4). Vault__Sync__Bisect gets api only to pass it to that download. No code path in core/actions/bisect/ calls write, batch (the write batch), delete, presigned_*, the branch index writer, Vault__Ref_Manager.write_ref, push or pull. A unit test greps the package's source for those names (test_Bisect__No_Write_Calls), so a later change that adds one fails.
• By test. test_Bisect__Nothing_Leaves_The_Clone runs a full run bisect over a two-clone setup on Vault__API__In_Memory and asserts:
• api._store (Vault__API__In_Memory.py:11) is byte-identical before and after;
• the clone's ref files, remote_heads.json, the local branch index file and reflog.jsonl are byte-identical;
• the other clone's pull afterwards reports nothing new.

6.4 Threat-model rows

• New accepted row (team/explorer/appsec/threat-model/v0.21.0__threat-model.md): TM-R4x — history bisect run executes code from historical commits in the working copy, actor A5 (a vault containing hostile files) and user error, L/M, accepted as in Git, mitigations 6.1, evidence test_Bisect__Runner.
• New fixed-by-design note in the coverage map: bisect never writes refs or the host, evidence 6.3.

7. Interactions

7.1 Other commands during a bisect

7.2 Head moved under the bisect

Every bisect command compares the clone head with state.branch_head. If they differ (another process, a manual edit), it continues and warns once: your branch head moved during the bisect (from X to Y); the bisect is unaffected and reset returns to Y.

7.3 Clone shapes

8. Performance

• Steps: ⌈log2(n)⌉ for n candidates; 1,000 commits → about 10 steps.
• Candidate set: one walk per command over commits between bad and the goods, with generations memoised in generations.json. Decrypting a commit is about 0.1–0.3 ms; 10,000 commits ≈ 1–3 s once, then the memo makes it near-instant. Weights: linear O(n); DAG bitsets O(n²/8) bytes (12.5 MB at 10,000), done in ms in Python integer ops.
• A step's working-copy cost follows the change between two commits, not the vault. diff_trees opens only differing folders; the guard verifies only touched paths (_scan_local_directory(verify=touched)); only changed files are written. On the 76,000-file vault (58,553 folders), a step between commits that differ by 300 files costs about what a 300-file pull's write costs (the pull of a 300-file pass measured 16.9 s in total, most of it fetch and flatten that a bisect step does not do). The first step from the head can be large (half the history's changes); later steps halve.
• Status during a bisect flattens the commit under test once; _flatten_incremental (Vault__Sub_Tree.py:186) derives it from a cached neighbour. The on-disk flat cache keeps two heads (FLAT_CACHE_ON_DISK = 2), so a long bisect evicts the head's entry; after reset the head is re-derived incrementally. Acceptable; no change.
• --no-checkout writes nothing: a step is the graph work plus whatever the test reads with sgit cat.
• Measure on the 76,000-file synthetic vault before release: start + 10 marks with and without --no-checkout, recorded in the CHANGELOG.

9. Test plan

All tests are real objects over Vault__API__In_Memory with Vault__Test_Env (fixed TEST_VAULT_KEY); no mocks, no __init__.py in test folders. Git is the oracle where the result is defined by Git (9.3); git is installed in CI's unit image (check, else mark those tests to skip when shutil.which('git') is empty, with a clear reason).

9.1 Files and classes

9.2 Cases (the synthetic histories)

Helper Bisect__History_Builder (in tests/_helpers/, a class) builds a vault with commits whose content is known: commit ck writes f.txt = k; from commit c11 on, bug.txt exists. The oracle command is test ! -f bug.txt (or a Python equivalent for Windows CI).

9.3 Git as the oracle

Test_Vault__Bisect__Graph__Git_Oracle builds the same commit graph in a scratch Git repository (git init, fixed author/committer dates) and in an sgit vault, runs git bisect start/good/bad and sgit's Vault__Bisect__Graph.best, and compares the position of the chosen commit (its message ck, since ids differ). Graphs where the choice is tie-free or where the tie rule is known to agree:

Also compared: the "N revisions left (roughly S steps)" numbers for each step, and the final "first bad commit" on cases 1, 4, 5, 13, 15. Skip picks after the first are not compared with Git (Git's order among equal distances is SHA-1 order); skip_away is tested against the formula vectors in 5.5 instead.

9.4 Acceptance checklist (implementation and deployment)

• [ ] sgit history bisect --help lists every subcommand of 3.1; sgit help all unchanged at the top level; test_CLI__B07__Namespace_Moves passes.
• [ ] Case 1 by hand on a real clone: four steps, Git's numbers, c11 is the first bad commit.
• [ ] Case 2 (run) exit 0; case 7 exit 2; case 9 exit 128; case 10 exit 1.
• [ ] Git-oracle tests pass (9.3).
• [ ] After reset, sgit status is clean and sgit history reflog has no new entry; .sg_vault/local/bisect.json does not exist.
• [ ] 6.3: host store and local refs byte-identical across a full run; the source-grep test passes.
• [ ] Every command in 7.1's "refused" rows refuses with the bisect message and changes nothing.
• [ ] Dirty-file guard: case 16 refuses, case 17 carries.
• [ ] Selective, scoped, shallow, read-only, pack, pack-store cases pass (25–29).
• [ ] --no-checkout mode: working copy untouched; sgit cat follows the commit under test.
• [ ] Crash recovery (case 19).
• [ ] Security tests in tests/security/test_Security__Fixed__Bisect.py pass; threat-model rows added.
• [ ] pytest tests/unit/ -n auto and pytest tests/security green; bandit baseline unchanged except the runner's subprocess lines, each with a # nosec B603 justification like Container__Command_Runner.
• [ ] Measured on the 76,000-file synthetic vault: start and per-step times with and without --no-checkout, in the CHANGELOG.
• [ ] CHANGELOG [Unreleased] entry; README "Git commands → sgit" table gains bisect.
• [ ] On the dev pre-release (pip install --pre sgit-ai): run case 1 against the live dev API with a scratch vault; confirm with the API's object listing that the vault's files did not change during the bisect.

10. Implementation steps (ordered commits)

Total: about 5–6 days. The roadmap's "1–2 days" covered the core loop only; the clone shapes, the refusals and the no-write proof are most of the work.

11. Open decisions for Dinis

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