phase: 136_force_push_reset

Everything is verified green and consistent. Final report:

**Phase 136 — final verification pass (all tasks already complete in `complete/136_force_push_reset/`):**

- **Verified implemented:** unified ff-or-reset update sequence in `scripts/git_sync.py::clone_or_pull` (phase-135 HEAD guard → shallow self-heal → `fetch origin <ref>` → `merge --ff-only` → on non-ff: SHA capture + `reset --hard FETCH_HEAD` + one WARNING line, returns normally); detached-HEAD fail-loud; `branch=None` legacy `git pull` deliberately gone
- **Completion criteria — all met:**
  1. ✅ Force push no longer fails sync (integration `test_clone_or_pull_force_push_resets_to_the_new_head` + API-seam `test_sync_pipeline_survives_a_force_push` + E2E run 2 asserts `success` and KB serves the V2 sentinel)
  2. ✅ Unrelated-history force push handled by the same reset (`test_clone_or_pull_unrelated_history_force_push_resets`)
  3. ✅ Broken fetch still fails loud (fetch-failure unit pins raise with no merge/reset argv; `test_main_git_failure_aborts_before_import`)
  4. ✅ WARNING line pinned: one line, 7-char SHAs, checkout path, `origin/<ref>`, no URL (unit exact-string pin + integration caplog pin)
  5. ✅ `uv run pytest --cov=app --cov-report=term-missing` → **3231 passed, app/ 99%**; `uv run pytest tests/e2e/test_force_push_resync.py -v --no-cov` → **2 passed in isolation** (10.6 s)
  6. ✅ Phase-135 pins preserved (mismatch guard, `--branch` clone argv, `branch=None` fresh-clone argv all green in the 53-test run)
- **Test/lint results:** `uv run pytest tests/unit/test_git_sync.py tests/integration/test_import_docs_git.py -v` → 53 passed; full suite 3231 passed (72 s); `uv run ruff check . && uv run pyright` → clean (0 errors)
- **Documentation:** README.md git-sources section already updated this phase to the ff-or-reset contract; all `.env.example` vars documented; pages table matches router; AGENTS.md rules and quick-reference commands verified accurate (rule 5 correctly documents the phase-100 §7.1 supersession) — **no changes needed**
- **Notable:** E2E "teeth" verification (fails on pre-phase code) is recorded in the task report; nothing was committed per harness protocol
- **Next pending phase:** `todo/137_pdf_image_context`

README.md

@@ -258,13 +258,20 @@ BOR_SOURCES_DIR=~/bor-sources   # default; each repo lands in <dir>/<repo-name>/
   <branch>` + `git merge --ff-only FETCH_HEAD`), and a checkout sitting
   on a *different* branch fails the sync loudly with a remove-and-
   re-add message (never a silent switch). Rows without a branch —
-  every pre-existing row and the env-fallback rows — keep the default
-  branch with byte-identical clone/pull behavior.
-- Every run **clones** (first time, full history) or **pulls**
-  (`git pull --ff-only`) each repo, then indexes the checkout. A legacy
-  shallow checkout is unshallowed once on its first post-phase-107 sync
-  (`git fetch --unshallow` — the one-time self-heal) so commit dates
-  stay real.
+  every pre-existing row and the env-fallback rows — track the
+  checkout's default branch (byte-identical clone behavior).
+- Every run **clones** (first time, full history) or brings an existing
+  checkout to the **head of the tracked branch** (phase 136: `git fetch
+  origin <branch>` + `git merge --ff-only FETCH_HEAD`) and then indexes
+  the checkout. If the remote was **force-pushed** — a fast-forward is
+  impossible — the checkout is reset hard to that head with one loud
+  log line **instead of failing the sync**: the checkout is a cache of
+  the remote head, and the KB is rebuilt from it on the same run, so a
+  force push is a logged, self-healing event. A genuinely broken fetch
+  (dead network, a branch deleted upstream) still fails the sync
+  loudly. A legacy shallow checkout is unshallowed once on its first
+  post-phase-107 sync (`git fetch --unshallow` — the one-time
+  self-heal) so commit dates stay real.
 - A failed sync aborts the run — no partial junk.
 
 ### Archive upload sources