feat(setup-swarm): broaden git reset allow-rule to all forms

.agents/references/hunk-agent-guide.md

@@ -0,0 +1,61 @@
+# Hunk Agent Guide
+
+How agents interact with a live Hunk session for code review.
+
+## Pre-requisites
+
+- Hunk must be running in a terminal (e.g. `git diff ... | hunk patch -`).
+- The Hunk session daemon auto-registers on startup.
+
+## Inspect
+
+```bash
+hunk session list
+git diff upstream/main...HEAD --diff-filter=M | hunk patch -
+```
+
+## Inspect
+
+```bash
+hunk session list                              # find live sessions
+hunk session get --repo .                    # confirm session repo match
+hunk session review --repo . --json          # file/hunk structure
+hunk session review --repo . --include-patch --json  # include raw diff text
+hunk session context --repo .                # current focus
+```
+
+## Navigate
+
+```bash
+hunk session navigate --repo . --file <path> --hunk <n>     # 1-based hunk
+hunk session navigate --repo . --file <path> --new-line <n>
+hunk session navigate --repo . --next-comment
+hunk session navigate --repo . --prev-comment
+```
+
+## Reload content
+
+```bash
+hunk session reload --repo . -- diff --exclude-untracked
+hunk session reload --repo . -- show HEAD~1
+```
+
+Always pass `--` before the nested Hunk command.
+
+## Add comments
+
+Single note:
+```bash
+hunk session comment add --repo . --file <path> --new-line <n> --summary "text" [--focus]
+```
+
+Batch:
+```bash
+printf '%s\n' '{"comments":[{"filePath":"...","newLine":N,"summary":"..."}]}' \
+  | hunk session comment apply --repo . --stdin [--focus]
+```
+
+## Common fixes
+
+- **"No active session matches repoRoot"** — pass session ID explicitly instead of `--repo .`.
+- **"No active Hunk sessions"** — Hunk is not running; ask the user to open it first.

.agents/references/hunk-user-guide.md

@@ -0,0 +1,57 @@
+# Hunk User Guide
+
+Quick reference for [Hunk](https://github.com/modem-dev/hunk) — the review-first terminal diff viewer used in this fork.
+
+## Open a diff (modified files only)
+
+```bash
+git diff upstream/main...HEAD --diff-filter=M | hunk patch -
+```
+
+`--diff-filter=M` shows only **modified** tracked files, excluding new/untracked files.
+
+## Navigation
+
+| Key | Action |
+|-----|--------|
+| `↑ / ↓` | move line by line |
+| `Space` or `f` | page down |
+| `b` or `Shift+Space` | page up |
+| `d / u` | half page down / up |
+| `[ / ]` | previous / next hunk |
+| `, / .` | previous / next file |
+| `{ / }` | previous / next comment |
+| `← / →` | scroll code horizontally (Shift = faster) |
+| `Home / End` or `g / G` | jump to top / bottom |
+
+## View
+
+| Key | Action |
+|-----|--------|
+| `1 / 2 / 0` | split / stack / auto layout |
+| `s` | toggle sidebar |
+| `t` | toggle theme |
+| `a` | toggle AI notes |
+| `z` | toggle unchanged context |
+| `l / w / m` | toggle line numbers / wrap / metadata |
+| `e` | open file in `$EDITOR` |
+
+## Review
+
+| Key | Action |
+|-----|--------|
+| `/` | focus file filter |
+| `c` | create review note |
+| `Tab` | toggle files/filter focus |
+| `F10` | open menus |
+| `r` | reload (watch mode) |
+| `q` | quit |
+
+## Mouse
+
+- Wheel — scroll vertically
+- Shift+Wheel — scroll horizontally
+
+## In-app help
+
+Press `?` or `h` inside Hunk to open the full controls help modal.

.claude/skills/fork-upstream-sync/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: fork-upstream-sync
+description: Sync this fork with new commits from unclebob/swarm-forge upstream. Identifies real conflicts (only files both sides modified since merge base), checks whether fork changes are superseded, migrates divergences to fork.bb, and opens a PR to gabadi/swarm-forge. Use when upstream has new commits, user says "sync upstream", "upstream has changes", or "merge upstream".
+---
+
+# Fork Upstream Sync
+
+## Core rule: only intersecting files are real conflicts
+
+After fetching upstream, find what each side changed since the merge base:
+
+```bash
+MERGE_BASE=$(rtk git merge-base HEAD upstream/main)
+rtk git diff "$MERGE_BASE"..HEAD --name-only          # our side
+rtk git diff "$MERGE_BASE"..upstream/main --name-only  # upstream side
+```
+
+Files only upstream changed → trivial forward merge, don't mention them.
+Files only we changed → no conflict.
+**Files in both lists → real conflicts. Analyze each one.**
+
+## Classify each real conflict
+
+For every intersecting file, answer in order:
+
+1. **Superseded?** Read upstream's new version and grep for the intent of our change. If upstream solved it already (even differently), our change is moot — take theirs.
+2. **Non-overlapping edits?** If our edit and upstream's are on different lines, take both — no decision needed.
+3. **Migration needed?** If upstream rewrote/replaced the file and we have substantive logic in it, extract our logic to `fork.bb` (see below).
+
+## Migration pattern: fork.bb
+
+When upstream replaces a script file we've extended, move our logic into `swarmforge/scripts/fork.bb`. This file is loaded by `swarmforge.bb` via `(load-file ...)` and is 100% fork-owned — zero conflict surface on future syncs.
+
+- Extractable: self-contained functions (settings writers, skill installers, sparse-checkout setup, prompt bundle resolvers)
+- Must stay in `swarmforge.bb`: config parsing for new fields, permission-mode flags, setup guards, load-file call itself
+- Keep the upstream file edits to small, stable hook call sites only
+
+## Resolving constitution/articles conflicts
+
+These files get edited by both sides frequently. Always:
+- Take upstream's structural/wording changes
+- Preserve our fork-specific rule insertions (check `rtk git diff "$MERGE_BASE"..HEAD -- <file>` to see exactly what we added)
+- Never remove an upstream rule unless there's an explicit ADR for it
+
+## Doing the merge
+
+```bash
+rtk git checkout -b feat/upstream-sync
+rtk git merge upstream/main
+# Files to take entirely from upstream:
+rtk git checkout --theirs <file> && rtk git add <file>
+# Manual resolutions: edit file, then rtk git add
+rtk git commit
+rtk git push origin feat/upstream-sync
+gh pr create -R gabadi/swarm-forge --title "..." --body "..."
+```
+
+**Never** open a PR against `unclebob/swarm-forge`. Always target `gabadi/swarm-forge`.
+`gh` CLI defaults to upstream — always pass `-R gabadi/swarm-forge`.
+
+## After the PR
+
+If any migrated divergences aren't yet documented, add an ADR row or manifest entry. ADR house style: divergence + why only, no rejected-options section.