Merge pull request #26 from netresearch/feat/worktree-convention-signed-commits

feat(refs): bare-worktree layout + signed-commit discipline

Author: CybotTM

skills/git-workflow/references/advanced-git.md

@@ -299,6 +299,60 @@ git worktree remove ../project-feature
 git worktree prune
 ```
 
+### Bare-Worktree Project Layout (Recommended)
+
+**One directory per branch; never switch branches in the same folder.**
+
+Rationale: IDEs that index the tree (gopls, Intellij, VS Code) choke on in-place branch switches, and running parallel work on feature branches without losing the main-branch state is painful. Using a bare repo with per-branch subdirectories gives you parallel checkouts, cheap hotfix spin-ups, and a main checkout that's never "dirty because I was exploring".
+
+```
+/projects/<repo>/
+├── .bare/          # bare git repository (clone --bare)
+├── main/           # main branch worktree
+├── feature-x/      # optional feature branch worktree
+└── bugfix-y/       # optional bugfix branch worktree
+```
+
+**Setup a new project this way:**
+
+```bash
+cd ~/projects
+mkdir <repo> && cd <repo>
+git clone --bare <repository-url> .bare
+
+# Make the bare clone behave like a regular origin fetch target.
+cd .bare && git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*" && cd ..
+
+# Check out main into a named subdirectory.
+git -C .bare worktree add ../main main
+```
+
+**Work on a new branch = create a new folder:**
+
+```bash
+git -C .bare worktree add ../feature-x feature-x    # or -b for a new branch
+cd feature-x
+# ... edit, commit, push ...
+cd ..
+git -C .bare worktree list          # audit trail of what's checked out
+git -C .bare worktree remove feature-x   # clean up when the PR merges
+```
+
+When removing a worktree leaves a dangling branch reference (e.g., after deleting the physical directory manually), `git worktree prune` in `.bare/` cleans up the metadata.
+
+**Batch cleanup after a session of PRs:**
+
+```bash
+# For each branch whose PR landed, delete the worktree + local branch:
+for wt in feature-x bugfix-y sync/template-foo; do
+  git -C /projects/<repo>/.bare worktree remove --force /projects/<repo>/$wt 2>&1 | tail -1
+  git -C /projects/<repo>/main branch -D "$wt" 2>&1 | tail -1
+done
+
+# Remote-side pruning (delete stale remote-tracking refs):
+git -C /projects/<repo>/main fetch --prune origin
+```
+
 ### Use Cases
 
 ```bash

skills/git-workflow/references/commit-conventions.md

@@ -436,4 +436,59 @@ git rebase -i --autosquash main
 4. **Reference issues**: Link commits to project management
 5. **Use scopes consistently**: Help with changelog generation
 6. **Don't include generated files**: Keep commits focused on source changes
-7. **Sign commits** (optional): Verify authorship with GPG
+7. **Always sign + signoff**: `git commit -S --signoff` — see next section
+
+## Signed Commits + DCO Sign-Off (Required)
+
+Run every commit with both flags explicit:
+
+```bash
+git commit -S --signoff -m "feat: add login endpoint"
+```
+
+**Why explicit `-S`.** Even with `commit.gpgsign=true` set globally, signing can silently fail in subprocess environments where the SSH agent isn't accessible. An explicit `-S` makes that failure visible instead of shipping an unsigned commit and finding out when branch protection rejects the push.
+
+**Why `--signoff`.** Adds the `Signed-off-by:` trailer. Required for DCO compliance on any repo that has the DCO check enabled (most netresearch repos do).
+
+**Sign-off identity must match `git config user.{name,email}`.** Mismatched identities fail the DCO check with an unhelpful "signoff required" error. Check before the first commit in a new worktree:
+
+```bash
+git config user.name
+git config user.email
+```
+
+**Never amend a commit with pre-commit-hook failures.** If the pre-commit hook fails, the commit **did not happen**. Running `git commit --amend` then modifies the PREVIOUS commit, which can destroy work. Fix the hook issue, re-stage, and create a new commit.
+
+**Never skip hooks** unless explicitly told to. `--no-verify`, `--no-gpg-sign`, and `-c commit.gpgsign=false` all bypass enforcement that exists for good reasons. If a hook fails, diagnose the root cause.
+
+## Atomic Commits
+
+Each commit should be a **single, self-contained logical change** that builds and passes tests independently.
+
+**Good:**
+
+- `feat: add user authentication endpoint` (one feature, complete)
+- `fix: correct SAML attribute name mapping` (one bug, fixed)
+- `chore(deps): bump go-ldap/ldap/v3 from 3.4.8 to 3.4.11` (one bump)
+
+**Bad:**
+
+- `feat: add auth + fix typo + update deps` (three unrelated concerns)
+- `wip` / `fixup` (leftover scratch commits)
+
+Rewrite messy history before opening the PR:
+
+```bash
+git rebase -i main        # interactive, squash / reword / reorder
+git rebase -i --autosquash main   # auto-pick fixup!/squash! commits
+```
+
+## Push Upstream on First Push
+
+When pushing a new branch for the first time, set upstream tracking with `-u`:
+
+```bash
+git push -u origin feature-branch
+```
+
+This makes subsequent `git pull` / `git push` work without specifying remote+branch. Without `-u`, everyone who clones the branch later has to set it up themselves.