distill: best practices from 2026-04-19 cross-project run

Adds 3 new topic files (ai-parallel-agents, api-integration,
python-patterns) and extends 21 existing topic files with new gotchas
and patterns surfaced from memory across tracked projects. Index
updated accordingly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

git-source-control.md

@@ -5,6 +5,11 @@
 - Use meaningful commit messages; prefer small, focused commits over large batches
 - Never commit secrets in plaintext — use SOPS + age or equivalent encryption
 - Enable pre-commit hooks where appropriate (secret detection, linting, formatting)
+- **Commit each implementation phase separately.** For multi-phase milestones, commit at each phase boundary with tests passing. Each commit should be self-contained and independently describable. Phase-by-phase commits surface issues early, keep history bisectable, and make later review and reflection far easier than one large end-of-milestone commit.
+
+## Repo Initialization
+
+- **Rename default branch immediately after `git init`.** `git init` still creates `master` on many systems despite `main` being the modern default. Run `git branch -m master main` (or configure `init.defaultBranch = main` globally) before first push — otherwise `git push -u origin main` fails with `src refspec main does not match any`. Bake this into any project-bootstrap script.
 
 ## Pre-Commit Hooks
 
@@ -12,6 +17,8 @@
 - Auto-encrypt files matching `.sops.yaml` rules that aren't yet encrypted
 - Enable with `git config core.hooksPath .githooks`
 - Consider secret detection, linting, and formatting hooks
+- **Copy hook scripts into `.git/hooks/`; don't symlink.** A symlinked hook resolves to the working-tree file, which changes on every branch switch — hooks then run stale (or wrong-branch) logic. Use an `install-hooks.sh` that copies the source script into `.git/hooks/`, and re-run it whenever the source changes.
+- **Document the sync-then-commit sequence when hooks require an up-to-date main.** If a pre-commit hook requires local `main` to match `origin/main`, the commit silently blocks when local `main` is even one commit behind. Standard sequence: `git checkout main && git pull --ff-only && git checkout <branch> && git rebase main`.
 
 ## GitOps Workflow
 
@@ -19,18 +26,43 @@
 - No manual changes without corresponding GitOps manifests — anything applied manually (e.g., `kubectl apply`, `helm install`) should immediately get a corresponding tracked manifest
 - For ArgoCD-managed clusters: edit in Git, push, sync — never edit live resources directly
 
+## Separate Data Repos from Code Repos for GitOps Controllers
+
+When a GitOps controller watches a git repo for declarative state (zone files, policy documents, config blobs), keep that data in a **repo separate from the controller's app code**. Mixing the two means every data change triggers CI builds (container rebuilds, test runs) for no reason, and pollutes the code repo's history with non-code churn.
+
+Separation yields:
+- Pure data commits with no CI noise
+- Cleaner webhook targeting per-repo
+- Independent access control for data editors vs code maintainers
+- Simpler rollback semantics — revert a data change without touching the controller image
+
 ## Remote Conventions
 
 - SSH workflows preferred over HTTPS for Git remotes
 - Use SSH config host aliases for multi-user setups (e.g., `gitea.example.com-<user>`)
 - Remote URL format: `git@<host-alias>:<org>/<repo>.git`
 - Optionally push-mirror to GitHub for public visibility
+- **Prefer internal hostnames for self-hosted Git remotes on the local network.** SSH push to a self-hosted Git server through a public/VPS hostname can return `kex_exchange_identification: read: Connection reset by peer`, especially during heavy agent activity — VPS routes often have connection limits or rate limiting that fail silently under load. On the local network, use the internal hostname in SSH aliases for heavy push workflows; reserve the public hostname for external access or HTTPS. Test with `ssh -T <alias>` immediately after configuring.
+
+## Cross-User Pushes
+
+- **Prefer SSH aliases over temp-URL swaps.** When a repo is owned by user A but your default SSH key authenticates as user B, configure a dedicated SSH host alias (`Host gitea.example.com-userA` with matching private key) and use `git@gitea.example.com-userA:org/repo.git`. Avoid temp-URL-swap (embedding an HTTPS token in the remote URL, pushing, then resetting) — it's clunky, prone to shell-quoting errors, and leaks tokens into reflog/history.
+- **API-created repos need the SSH user as a collaborator.** If a repo is created via API token (user A) but pushes use an SSH alias authenticating as user B, user B has no access by default. Add the SSH-authenticating user as admin collaborator via API before the first push. Applies to Gitea, GitHub, and any platform where API auth and SSH auth use different identities.
 
 ## Access and Clone Gotchas
 
 - **Org repos require explicit collaborator grants.** Don't assume organizational membership implies write access — verify permissions before setting up automation or CI/CD.
 - **Shallow clones break push operations.** `git clone --depth 1` is fine for read-only CI jobs, but pipelines that push artifacts, tags, or mirror to other remotes need full clones.
 
+## Cross-Remote Hygiene for Multi-Remote Projects
+
+When a project has divergent remotes (e.g., local Gitea with granular commits + GitHub with squash-merged PRs), histories diverge and naive merges explode.
+
+- **Never `git merge <remote>/<branch> --allow-unrelated-histories`** — it produces 50+ mass conflicts across unrelated files.
+- **Import specific files instead:** `git checkout <remote>/<branch> -- <specific-files>` brings those paths in as a normal local change.
+- **Always diff after a bulk checkout.** `git checkout` from a remote silently overwrites locally-modified files with older remote versions with zero warning. Run `git status` and review each touched file before staging; restore with `git checkout HEAD -- <file>` if an unwanted overwrite happened.
+- **After an upstream PR squash-merge, reset — don't rebase — local branches to main.** Rebase against a squashed history leaves phantom commits; a clean `git reset --hard origin/main` on the local branch is correct.
+
 ## Version Management
 
 - Use the latest stable version of dependencies unless pinned for a reason
@@ -55,7 +87,3 @@ When running parallel agents or tasks that modify the same repo:
 - Tasks with multiple dependencies get an octopus merge base branch
 - Worktrees share the `.git` object store — fast creation, minimal disk usage
 - Keep containers detached (`docker run -d`, not `--rm`) so logs survive for inspection after exit
-
-## API-Created Repos Need SSH User as Collaborator
-
-If a repo is created via API token (user A) but pushes use an SSH alias authenticating as user B, user B has no access by default. Add the SSH-authenticating user as admin collaborator via API before the first push. This applies to Gitea, GitHub, and any platform where API auth and SSH auth use different identities.