claude_mac/.claude/tasks/plans/2026-10-06-manual-push-mode-1632.md

# PLAN — manual-push-mode (run A) — REVISED after challenge r1 + confirmation r2
Contract: .claude/tasks/contracts/2026-10-06-manual-push-mode-1632.md

## Context
`gitflow.autopush` (git config, default true) already silences the post-commit/post-merge push hooks and `_gitflow_delete_remote`. Gap: `_gitflow_push_branch` (lib/gitflow.sh:78-88) only reads `GITFLOW_NO_PUSH`, so `start`/`finish` push even in manual mode. `hooks/unpushed-guard.sh` nags at every Stop regardless of mode. Doctrine says unpushed = defect, which would drive Claude to push by hand.
Challenge r1 added: (a) in manual mode a branch's upstream lags, and `git branch -d` checks the UPSTREAM when one is set (LRN-161), so `gitflow_delete` would refuse after a successful merge (rc 5, false "unmerged"); (b) `git pull --ff-only … || true` swallows a diverged base silently, which only auto-push used to surface; (c) `_gitflow_delete_remote` skipping leaves `origin/<br>` behind with no word; (d) skills push on their own (`/capitalize` STEP 5C `git push origin develop`, client-handover, release-candidate/tour "already on origin" claims) and settings.json prose says unpushed = defect → run C (skills) and run B (settings), see contract.

## Checklist
- [ ] lib/gitflow.sh — add `_gitflow_push_off()` right above `_gitflow_push_branch`: rc 0 when `GITFLOW_NO_PUSH=1` OR `git config --bool --default true gitflow.autopush` is `false`. Comment: "GITFLOW_NO_PUSH=1 (throwaway test repos) or gitflow.autopush=false (manual-push mode, human-set: work machine, foreign clone)". Call it as the first line of `_gitflow_push_branch`. In `_gitflow_delete_remote` KEEP `[ "${GITFLOW_NO_PUSH:-0}" = 1 ] && return 0` as the first line (test repos stay silent), then replace the inline autopush line with `_gitflow_push_off && { <left-in-place note, item 2>; return 0; }`. Grep claim, scoped: outside the hook-emitter heredocs (`_gitflow_emit_push_hook`, untouched per AC7) and that one documented NO_PUSH line, no inline reader of the two flags remains in lib/gitflow.sh.
- [ ] lib/gitflow.sh — `_gitflow_delete_remote`: when `_gitflow_push_off` fires (NO_PUSH already returned above, so this is autopush=false), origin exists, and `git rev-parse -q --verify "refs/remotes/origin/$br" >/dev/null` succeeds (no network), print to stderr `gitflow: origin/<br> left in place (manual push mode) — by hand: git push origin --delete <br>`; return 0 either way. Every `rev-parse --verify` probe added by this plan ends in `>/dev/null`: `gitflow_start`'s stdout is the branch name only (T11).
- [ ] lib/gitflow.sh — `gitflow_delete`: after `gitflow_merged_into_base` passes, check out the base that CONTAINS the branch: `if git merge-base --is-ancestor "$br" "$GITFLOW_DEVELOP" 2>/dev/null; then git checkout -q "$GITFLOW_DEVELOP"; else git checkout -q "$GITFLOW_MAIN"; fi` (replaces the current develop-else-main fallback at line ~195; T22j = merged into main only must stay deletable). Then `git branch -q --unset-upstream "$br" 2>/dev/null || true` BEFORE `git branch -q -d "$br"`. Comment citing LRN-161: `-d` judges against the upstream when one is set, against HEAD otherwise; the ancestor check is the real gate, so HEAD must be the containing base and the upstream must be out of the way. Keep the ≤25-logic-line budget: extract `_gitflow_checkout_containing_base <br>` if needed.
- [ ] lib/gitflow.sh — add `_gitflow_sync_base()` (≤10 lines) replacing the two `git pull --ff-only -q 2>/dev/null || true` lines (gitflow_start, _gitflow_merge_into): `_gitflow_timeout git pull --ff-only -q >/dev/null 2>&1 && return 0`; then if `git rev-parse -q --verify '@{u}'` succeeds and `git rev-list --count HEAD..@{u}` > 0 → stderr `gitflow: <branch> is behind origin/<branch> by <n> and cannot fast-forward — reconcile by hand (git pull, then push)`; always return 0 (never blocks). Silent when: no upstream (`@{u}` unresolvable), or offline with no RECORDED divergence (HEAD..@{u} = 0). Offline after an earlier fetch recorded the base as behind → still warns (the recorded fact is true). The `@{u}` probe ends in `>/dev/null`.
- [ ] hooks/unpushed-guard.sh — mode detection after `br=`: `raw=$(git config gitflow.autopush)`; `manual=0`; `[ "$(git config --bool --default true gitflow.autopush 2>/dev/null)" = false ] && manual=1`; `invalid=0`; `[ -n "$raw" ] && ! git config --bool gitflow.autopush >/dev/null 2>&1 && invalid=1`. Stop + manual → `exit 0` immediately (BDR-087: message only, and the user chose silence at Stop). ONE clause function kept (`unpushed_clause`), mode-aware: auto path unchanged byte for byte (T1–T9). Manual path: `n=$(git rev-list --count --branches --not --remotes)` (ALL local branches, not just HEAD — a session usually starts on develop after a local finish); `n -eq 0` → empty (so a fresh `start` branch with 0 commits is silent, LRN-091); else list the ahead branches via `git for-each-ref --format='%(refname:short)' refs/heads` filtered on `git rev-list --count <b> --not --remotes` > 0, joined by `, ` → clause `<n> commit(s) not on origin (<b1>, <b2>), push by hand: git push -u origin <first listed ahead branch>` (never HEAD's name: HEAD may hold no unique commit); no origin remote → `no 'origin' remote, <n> commit(s) on this disk only`. Prefix chosen at the single emit site: auto `⚠ unpushed work:`, manual `ℹ manual push mode:`. SessionStart keeps the `; <d> uncommitted change(s) in <cwd>` clause in both modes (dirty-only manual → `ℹ manual push mode: <d> uncommitted change(s) in <cwd>`). `invalid=1` → SessionStart appends `; gitflow.autopush='<raw>' is not a boolean, treated as auto (pushes run)`. Header comment: +3 lines on manual mode. Functions ≤25 logic lines: extract `ahead_branches()`.
- [ ] CLAUDE.global.md — gitflow section: replace the two sentences `Foreign clone: \`git config gitflow.protect false\` / \`gitflow.autopush false\`; \`GITFLOW_NO_PUSH=1\` only for throwaway test repos. A branch ahead of its upstream is a defect, not a state.` (lines 186-188) with ONE statement: `Human-set opt-outs: \`git config gitflow.protect false\` (foreign clone) and \`gitflow.autopush false\` = manual-push mode (work machine): branches, commits and local merges run as usual, nothing is pushed, Claude never pushes (\`/close\` included) unless the user asks; \`GITFLOW_NO_PUSH=1\` only for throwaway test repos. Outside manual mode a branch ahead of its upstream is a defect, not a state.` Line 229 bullet: append ` Manual-push mode (above) is the one exception.` Net +3 to +4 lines (312 → ≤316, budget 320). No heading or bold label changes (doctrine-citers census unaffected).
- [ ] lib/gitflow-test.sh — NEW isolated block after T18g, before T19: `echo "T18m — manual-push mode: gitflow.autopush=false (human-set) → nothing pushed, finish still deletes"`; `newrepo manual; echo a>a; hookon; gitflow_init`; bare origin; `git push -q -u origin main develop` (`-u`: develop MUST track origin/develop for T18l/T18n — gitflow_init creates develop untracked, and manual mode never sets it); precondition chk `T18m0 develop tracks origin/develop`: `git rev-parse -q --verify 'develop@{u}' >/dev/null`; `git config gitflow.autopush false`. ORDER inside the block: T18i, T18j, T18k, T18o, T18n, T18l (T18l fetches `o` into refs/remotes/origin/develop and nothing reconciles it, so an offline test after it would warn — T18n runs first, while develop is ahead-only).
    T18i: `gitflow_start feature manual` → `git rev-parse --verify -q refs/heads/feature/manual` AND `! git ls-remote --exit-code --heads origin feature/manual`.
    T18j: `echo m>m.txt; git add m.txt; git commit -q -m m`; `# shellcheck disable=SC2034` + `dev_remote_before=$(git -C "$bare" rev-parse develop)`; `fin_rc=0; gitflow_finish >/dev/null 2>&1 || fin_rc=$?` → rc 0, `Merge feature/manual into develop` in local develop log, origin develop == dev_remote_before, branch deleted.
    T18k (lagging upstream): `git config gitflow.autopush true; gitflow_start feature lag` (pushed -u); `git config gitflow.autopush false; echo l>l.txt; git add l.txt; git commit -q -m l`; `lag_out=$(gitflow_finish 2>&1); lag_rc=$?` → rc 0, `! git rev-parse --verify -q refs/heads/feature/lag`, origin/develop still == dev_remote_before, `lag_out` contains `left in place`, `git ls-remote --exit-code --heads origin feature/lag` still exists.
    T18o (NO_PUSH stays silent on the remote copy): `git config gitflow.autopush true; gitflow_start feature np` (pushed -u); `git config gitflow.autopush false; echo n>n.txt; git add n.txt; git commit -q -m n`; `np_out=$(GITFLOW_NO_PUSH=1 gitflow_finish 2>&1); np_rc=$?` → rc 0, branch deleted, `np_out` does NOT contain `left in place`, origin/feature/np still exists.
    T18n (offline, no recorded divergence → silent): `git remote set-url origin /nonexistent/x.git; off2_out=$(gitflow_start feature off2 2>&1)` → does NOT contain `behind`, `git rev-parse --verify -q refs/heads/feature/off2`; `git remote set-url origin "$bare"; git checkout -q develop`.
    T18l (diverged base warning): `other="$WORK/manual-other"; git clone -q "$bare" "$other"`; in other: hooks off, identity, `git checkout -q develop; echo o>o.txt; git add o.txt; git commit -q -m o; git push -q origin develop`; local (on develop, ahead by the local merges): `div_err="$WORK/div.err"; div_out=$(gitflow_start feature div 2>"$div_err")` → stdout `[ "$div_out" = feature/div ]` (no SHA leak), stderr `grep -q 'behind origin/develop' "$div_err"`, branch exists.
    Every `*_out`/`*_rc`/`dev_remote_before` read only inside chk evals gets `# shellcheck disable=SC2034` on the line above (lib/gitflow-test.sh idiom, lines 296/344/353).
- [ ] lib/tests/unpushed-guard.test.sh — append before the PASS line (repo has origin, upstream on main/master, in sync after T8's push; tree dirty from T7/T8 → `git checkout -q -- a` first):
    `git config gitflow.autopush false`
    T10 manual + clean + in sync: SessionStart → `silent`; Stop → `silent`.
    T11 one local commit on HEAD, plus `git branch side HEAD; git checkout -q side; echo s>s; git add s; git commit -q -m s; git checkout -q -` (second ahead branch): Stop → `silent`; SessionStart → contains `manual push mode`, `2 commit(s)`, `side`, and NOT `unpushed work`.
    T12 fresh branch with no upstream and 0 extra commits (`git checkout -q -b fresh`): SessionStart → still reports the 2 commits (they are reachable from other branches; count is repo-wide) — assert `2 commit(s)`; then `git checkout -q -` .
    T13 dirty tree only (push the two commits by hand in the test: `git push -q origin HEAD side`, then `echo d>>a`): SessionStart → contains `manual push mode` and `uncommitted`, NOT `commit(s) not on origin`; Stop → silent. `git checkout -q -- a`.
    T14 invalid value: `git config gitflow.autopush flase`; one more local commit; SessionStart → contains `not a boolean` AND `unpushed work` (treated as auto); Stop → contains `1 commit(s)` (auto behaviour).
    T15 toggle back: `git config --unset gitflow.autopush`; Stop → contains `1 commit(s)` (positive control, auto path intact).
    T16 no-origin manual (LAST, nothing restored after): `git config gitflow.autopush false; git remote remove origin`; SessionStart → contains `manual push mode` and `no 'origin' remote`; Stop → silent.

## Edge cases
- `gitflow.autopush` set `--global` on the work machine: `git config --bool --default true` reads the merged value → every repo, no code difference. Toggle is human-set (static deny on `git config gitflow.*`, BDR-095 c); the deny is prefix-based and run B widens it (`git config * gitflow.*`, `git -c gitflow.*`, `GIT_CONFIG_COUNT=*`).
- Garbage value: `--bool` fails → auto mode (fail-open toward pushing, pre-existing in the emitted hooks, which run A may not edit — AC7); the guard now SAYS so at SessionStart. Fail-closed is a run B question (hook emitters).
- Count scope: manual mode counts every local branch (`--branches --not --remotes`); auto mode keeps the current-branch count (unchanged contract, T5/T6).
- Diverged base: warning only, never blocks `start`/`finish`; the user reconciles by hand. No upstream → silent; offline with no recorded divergence → silent; offline after a fetch already recorded the base as behind → warns (true fact).
- `gitflow_delete` now ends on the base that contains the branch (main for a main-only merge, develop otherwise) instead of always develop; no test asserts HEAD after a delete.
- No emitter (`_gitflow_emit_*`) touched → T19 drift gate needs no regeneration.
- Deployment order (contract): `gitflow.autopush false` must not be set on the work machine before runs B (push-guard, settings) and C (skills that push) are merged; until then `/close` STEP 5C still pushes develop.

## Disposition (STEP 0.6 + challenge r1)
- honors BDR-095 by extending the existing `gitflow.autopush` opt-out (amendment c), not a new key.
- honors BDR-100 / LRN-113 by (1) one shared predicate `_gitflow_push_off` for every lib push site, (2) surface grep widened to `grep -rn "git push\|autopush\|GITFLOW_NO_PUSH" lib hooks githooks skills agents settings.json CLAUDE.global.md` — the skill/agent/settings hits are assigned to runs B and C in the contract, not silently dropped.
- honors LRN-161 by `--unset-upstream` before `-d` (the ancestor check is the gate; `-d` must judge against HEAD) and by re-reading the `--ff-only` pulls (now warn on divergence, wrapped in `_gitflow_timeout`).
- honors LRN-104 by locking every new output string in a test: manual line (T11), dirty-only (T13), invalid value (T14), no-origin (T16), "left in place" (T18k) and its NO_PUSH silence (T18o), "behind origin" (T18l) and its offline silence (T18n), stdout purity of `start` (T18l).
- honors LRN-091 / LRN-047 by silence at Stop and at `n=0` in manual mode.
- BDR-087: Stop hook stays systemMessage-only; no control flow.