# PLAN — gitconfig-autopush (feat) — REVISED v4 (round 1 + user spec + confirmation pass, default true) Contract: .claude/tasks/contracts/2026-10-07-gitconfig-autopush-1734.md Branch: feature/gitconfig-autopush (off develop) ## Goal (user spec, verbatim constraints in the contract) 1. `gitconfig` template, section `[core]`: fixed line `hooksPath = ~/.claude/githooks` (git expands `~` itself for core.hooksPath; no absolute path, no expansion by the script; the installer neither creates nor checks that directory). 2. install.sh asks at install: automatic push by the gitflow hooks on this machine? `[true/false]` (default: true — user correction). Answer rendered into a new section `[gitflow]` / `autopush = @AUTOPUSH@`. - Only the exact strings `true` and `false` are accepted. Anything else re-asks; an empty answer gives `true`. - The render FAILS explicitly (grep after render) if `@AUTOPUSH@` is still in the final content. A non-boolean value blocks every push on the machine (fail-closed), so a leaked placeholder would be a silent outage. - Non-interactive install: env `DOTFILES_GITFLOW_AUTOPUSH=true|false`, default true. 3. Keep the existing backup (`~/.gitconfig.backup-`). Do not touch the other template sections. 4. Human-gated 2026-10-07 (kept from round 1): fix the identity call site so the deployed file carries the resolved name/email, not the literal `@USER@`/`@EMAIL@`. 5. The user sees the full diff BEFORE anything is committed (working tree only until then). ## Context (verified) - `gitconfig` is a template; `render_identity_template` (install.sh:497) replaces @USER@/@EMAIL@ by bash substitution over every line (comments included). - `deploy_gitconfig` (install.sh:532) takes an rc PATH and reads USER/EMAIL from it. BUG: the call site install.sh:688 passes `"$SCRIPT_DIR/$bashrc"` = the repo TEMPLATE whose exports are `export USER="@USER@"` (bash/bashrc-linux:33-34). The placeholders are non-empty, the guard passes, the deployed file reads `name = @USER@`. - Identity resolved at install.sh:584-585 into `identity_name` / `identity_email`, before package installs (prompts first). EMAIL default "" when no tty and no env. - Readers (~/.claude/lib/gitflow.sh gitflow_push_mode, post-commit/post-merge hooks): `git config --bool gitflow.autopush` → false = manual, true/unset = auto, other = invalid → nothing pushed (fail closed). Only exact `true`/`false` are ever written. - `core.hooksPath` is a pathname-typed key: git tilde-expands `~/.claude/githooks`. Today `make link` writes it with `git config --global`; the redeploy dropped it. With the fixed template line the redeploy keeps it and the file matches the render again. - This session's permission layer denies every `git config … gitflow.*` command, so the installer and the oracle must NOT read or write the key through git: an existing value is read from ~/.gitconfig with sed (same shape as rc_export_value). Trade-off: a value set in XDG/system/included config is not seen; ~/.gitconfig is the only file written. - install.sh runs under macOS /bin/bash 3.2 before brew bash exists (LRN-014): plain string compares only, no `${var,,}`. - The repo has no test suite and install.sh has no --dry-run: the oracle harness below is the test, run by the contract gate. ## Checklist [ ] gitconfig — header comment (lines 1-4) reworded WITHOUT literal placeholder tokens (today it renders as "bchanot and x@y are replaced at install time"): "Template for the user-scope ~/.gitconfig, rendered by install.sh. Git never expands $VARS, so the identity and the gitflow push mode are placeholders filled at install time with the installer's answers. A repo .git/config still overrides these values for that repo." In `[core]`, after `excludesfile`, add the fixed line: hooksPath = ~/.claude/githooks with a one-line comment above it: "# gitflow hooks (created by `make link` in claude-config); git expands ~ itself." After `[user]`, add: [gitflow] # Push mode of the gitflow hooks: false = manual, you run `git push`; # true = every commit and merge is pushed. Exact true/false only (fail-closed). autopush = @AUTOPUSH@ 4-space indent like the other keys. No other section touched. [ ] install.sh — two new functions right after `resolve_identity` (~line 525), tabs: # Ask the push question on the terminal until the answer is exactly true or false; # Enter (or EOF) = true. Prints the value. ask_autopush() { local answer="" while :; do read -rp "Automatic push of commits by the gitflow hooks on this machine? [true/false] (default: true) " answer || true case "${answer:-true}" in true|false) printf '%s\n' "${answer:-true}"; return 0 ;; *) echo "Answer exactly true or false." >&2 ;; esac done } # Push mode of the gitflow hooks (gitflow.autopush), exact true/false only: the # readers fail closed on anything else. Never asked twice: a true/false already in # ~/.gitconfig wins silently (read with sed, like rc_export_value, so a hand-set # value survives the redeploy; a non-exact spelling is named and re-asked), else # DOTFILES_GITFLOW_AUTOPUSH (anything but true/false aborts the install here, # before any file is touched, whatever ~/.gitconfig holds), else the prompt # on a terminal, else true (today's unset = auto). Prints the value. resolve_autopush() { local value="" preset="${DOTFILES_GITFLOW_AUTOPUSH:-}" case "$preset" in true|false|"") ;; *) echo "DOTFILES_GITFLOW_AUTOPUSH='$preset' — must be exactly true or false" >&2; return 1 ;; esac if [ -f "$HOME/.gitconfig" ]; then value="$(sed -n 's/^[[:space:]]*autopush[[:space:]]*=[[:space:]]*//p' "$HOME/.gitconfig" | tail -n 1)" case "$value" in true|false) printf '%s\n' "$value"; return 0 ;; "") ;; *) echo "gitflow.autopush='$value' in ~/.gitconfig is not exactly true/false — asking again" >&2 ;; esac fi if [ -n "$preset" ]; then printf '%s\n' "$preset"; return 0; fi if [ -t 0 ]; then ask_autopush; else echo true; fi } Order: preset syntax is validated FIRST (a bad preset always aborts, even on a re-run), then an existing exact value wins, then a valid preset, prompt, default. Each ≤ 25 logic lines. `read … || true` on EOF → empty → true → loop ends. [ ] install.sh — after `set -euo pipefail` (line 4) add, with a one-line comment ("bash ≥ 5.2 expands `&` in ${var//pat/rep} replacements: an `&` in a name would corrupt the rendered identity; no-op on bash 3.2"): shopt -u patsub_replacement 2>/dev/null || true [ ] install.sh — main sequence, right after identity_email (line 585): autopush="$(resolve_autopush)" (set -e: a `return 1` from an invalid preset aborts the install right here.) [ ] install.sh — `deploy_gitconfig` becomes `deploy_gitconfig ` (no rc path, no rc_export_value call): local name="$1" email="$2" autopush="$3" rendered backup if [ -z "$name" ] || [ -z "$email" ]; then echo "Name or email empty — skipping ~/.gitconfig (push mode $autopush not written)" >&2 return 0 fi rendered="$(render_identity_template "$SCRIPT_DIR/gitconfig" "$name" "$email")" case "$autopush" in true|false) ;; *) echo "gitconfig render refused: push mode '$autopush' is not exactly true/false — nothing written" >&2 return 1 ;; esac rendered="${rendered//@AUTOPUSH@/$autopush}" case "$rendered" in *@AUTOPUSH@*) echo "gitconfig render failed: @AUTOPUSH@ left in the output — nothing written" >&2 return 1 ;; esac (no pipe: `printf | grep -q` under pipefail can read SIGPIPE as "no leak") … cmp/skip, backup, write unchanged … echo "Deploying gitconfig to ~/.gitconfig ($name <$email>, autopush=$autopush)" Header comment rewritten: $1 $2 = the identity rendered into the rc, $3 = push mode; one line on the two fail-closed checks. If > 25 logic lines, extract `render_gitconfig ` (render + substitution + grep). [ ] install.sh:688 call site → `deploy_gitconfig "$identity_name" "$identity_email" "$autopush"` comment: "User-scope git config, same identity as the rc just rendered." [ ] README.md:31 gitconfig row — "`@USER@`, `@EMAIL@` and `@AUTOPUSH@` (gitflow push mode) are filled at install with the installer's answers; `core.hooksPath` points at the gitflow hooks `make link` creates." [ ] README.md:50 — "(identity, push mode, macOS shell, offers)". [ ] README.md:70 step 6 — replace "with the same `USER` / `EMAIL`" by "with the same name and email", then add: the installer asks once whether the gitflow hooks push every commit and merge (`true`/`false` exactly, Enter = `true`); a `true`/`false` already in `~/.gitconfig` is reused without asking and survives the redeploy; `DOTFILES_GITFLOW_AUTOPUSH=true|false` presets it for a non-interactive install (no terminal and no preset → `true`; any other preset aborts the install); the render refuses to write a file where `@AUTOPUSH@` leaked, since a non-boolean value blocks every push. To switch later: `git config --global gitflow.autopush true|false`. [ ] CLAUDE.md:25 — `gitconfig user-scope ~/.gitconfig template, @USER@/@EMAIL@/@AUTOPUSH@ (gitflow push mode, exact true/false) filled at install; core.hooksPath fixed` [ ] .claude/tasks/contracts/check-autopush-render.sh — oracle harness (LRN-011 pattern): `set -euo pipefail`; `cd "$(git rev-parse --show-toplevel)"` (the only git call, no config access); `SCRIPT_DIR="$PWD"`. Extract ask_autopush, resolve_autopush, render_identity_template, deploy_gitconfig (and render_gitconfig if extracted) from install.sh via `sed -n '/^fn() {/,/^}/p'` into `$(mktemp)` and source it. `fresh_home() { HOME="$(mktemp -d)"; export HOME; }` before every case; guard `case "$HOME" in /tmp/*|/private/*|/var/*) ;; *) fail "refusing HOME=$HOME";; esac` before any deploy call. No rm of temp dirs (never rm -rf through a variable). `fail() { echo "FAIL: $*" >&2; exit 1; }`; every assertion goes through it. stderr captures go to `"$HOME/err"` (the scratch HOME), never a relative path in the repo. Header comment: "Oracle for the contract: exercises install.sh functions on scratch HOMEs under mktemp; never reads or writes the real ~/.gitconfig and never calls git config." If the permission layer refuses a step of this harness, the refusal is reported with its rule and the harness is handed to the user to run; it is never reworked to get around the rule. Case A (render): fresh_home; DOTFILES_GITFLOW_AUTOPUSH=false err; rc=$?; set -e` → rc != 0, err contains "@AUTOPUSH@", no ~/.gitconfig written. (Passing the placeholder as the value is the only way to make the substitution a no-op; it stands in for a broken template.) Case C (existing wins): fresh_home; printf '[gitflow]\n autopush = true\n' > "$HOME/.gitconfig"; DOTFILES_GITFLOW_AUTOPUSH=false err; rc=$?; set -e` → rc != 0, err contains "exactly". Case F (prompt loop): `printf 'yes\ntrue\n' | ask_autopush 2>err` → true, err contains "exactly"; `printf '\n' | ask_autopush` → true. Case G (empty email): deploy_gitconfig x "" true 2>err → no file, err has "not written". Case H (call site): `grep -q 'deploy_gitconfig "\$identity_name" "\$identity_email" "\$autopush"' install.sh` and `! grep -q 'deploy_gitconfig "\$SCRIPT_DIR' install.sh`. Case I (idempotent): run right after Case A in Case A's HOME (no fresh_home between them): deploy_gitconfig x x@y false again → stdout contains "already up to date", no `.gitconfig.backup-*` created. Case J (non-exact existing): fresh_home; printf '[gitflow]\n autopush = off\n' > "$HOME/.gitconfig"; env unset, "$HOME/err"; rc=$?; set -e` → rc != 0, err contains "not exactly", no file. Print AUTOPUSH_RENDER_OK only at the end. ## Edge cases - Non-exact existing value: `off`/`no`/`0` are VALID false for the readers (`--bool`), `maybe` is invalid (nothing pushed). Neither is reused (strict grammar): the value is named on stderr, then preset/prompt/default decide. With no tty and no preset a hand-set `off` becomes `true`: accepted consequence of the strict grammar + default true, documented in the README sentence on switching the mode. - Re-run: value found in ~/.gitconfig → no prompt → identical render → "already up to date — skipping" (now holds with hooksPath in the template). - No tty (curl | bash without /dev/tty) and no preset → true: same as today's unset = auto. - Invalid preset aborts before Oldconfig/rm or any write (resolution happens at the identity step). - Empty email → file skipped, dropped push mode named in the warning. - `.githooks/post-commit` / `.githooks/post-merge` are dirty from the session hook refresh: do not touch, do not stage. - Known, not handled: a system-scope `/etc/gitconfig` value is shadowed by the written global one (blockers entry at CAPITALIZE). ## Tests - `bash -n install.sh`, `shellcheck install.sh`. - `bash .claude/tasks/contracts/check-autopush-render.sh` → AUTOPUSH_RENDER_OK. ## Disposition (memory read-before) - honors BDR-001 (bash) — bash substitutions, `read -rp`. - honors BDR-002 — template read via `$SCRIPT_DIR/gitconfig`. - BDR-012 pattern (installer prompts, re-ask on bad input, keep-existing, no TTY → default) honored on the interactive path; DEVIATION flagged: an invalid DOTFILES_GITFLOW_AUTOPUSH preset aborts the install (user's fail-closed requirement), before any file is touched. - honors LRN-001 idempotency — unchanged ~/.gitconfig skipped; existing value reused. - honors LRN-011 — oracle is a stub harness on extracted functions, no live install, no git config. - honors LRN-014 — bash 3.2 safe. - Non-binding: BDR-016 (backup naming, kept as is). ## CHALLENGE SUMMARY (round 1 → v2) - BLOCKER (correctness+robustness): template path at the call site → placeholders deployed → closed: deploy_gitconfig takes name/email/autopush; call site passes the resolved identity; Case A asserts no placeholder; Case H pins the call site. [gated] - BLOCKER (simplicity+robustness): `git config … gitflow.*` denied to this session → closed: sed read of ~/.gitconfig, harness writes files directly, zero config access. - MAJOR: loose boolean grammar / fail-open normaliser → superseded by the user spec: exact true/false only, re-ask, default true (user correction), invalid preset aborts. - MAJOR: empty email drops the answer → closed: named in the skip warning. - MAJOR: hooksPath wiped on redeploy → superseded by the user spec: fixed template line. - MAJOR: shared scratch HOME → closed: fresh_home per case + guard. - MINORs: header comment reworded, `@(USER|EMAIL|AUTOPUSH)@` assertion, README:50, README wording (precedence + how to switch), call-site grep. Deferred: system-scope shadowing. - Added by the user spec: fail-closed grep after render (Case B), DOTFILES_ prefix. ## CHALLENGE SUMMARY (confirmation pass, v3 → v4): SOLID, 8 MINOR - Accepted: preset validated first; non-exact existing value named; positive true/false guard + no-pipe leak check; patsub_replacement off + Case A2; err files in scratch HOME; Case I in Case A's HOME; harness header + refusal rule; TODO line rewritten. - Edge-case text corrected (off/no/0 are valid false for the readers). - BDR-012 deviation (preset abort) flagged in the Disposition.