docs: add fork workflow documentation

[dashed]

Summary

Adds FORK_WORKFLOW.md documenting the modular feature branch strategy for maintaining this fork.

Contents

• Overview of the branch strategy (main tracks upstream, feature branches based on main, integration merge via jj)
• Remote configuration (origin = fork vs upstream = NousResearch/hermes-agent)
• Jujutsu (jj) setup and common commands
• Step-by-step guides for:
  • Updating main from upstream
  • Adding new features (create a dedicated branch off main, then rebuild the integration merge)
  • Dropping features absorbed or superseded upstream (skip them when rebuilding the integration merge rather than rebase stale duplicates)
• Integration branch (dashed/my-hermes) explanation
• Workflow tips and troubleshooting

Why on its own branch?

This file was previously added directly to the integration merge commit and was lost when the integration was rebuilt. Files on the integration branch are dropped on every rebuild — only files on dedicated feature branches survive. This PR ensures FORK_WORKFLOW.md persists across integration rebuilds.

That rule has earned its keep: since this PR was opened, two sibling feature branches (fix/slack-mrkdwn-formatting, fix/container-systemctl-status) have been absorbed/superseded upstream and dropped from the integration. Without dedicated branches they would have been silently lost on the next rebuild. As of 2026-04-12, docs/fork-workflow is the only active feature branch remaining in the integration merge.

Current state

• Rebased onto upstream 0d0d27d4 (2026-04-12)
• Single docs commit, mechanical rebase from 8b861b77 → 0d0d27d4, no conflicts
• Current head: d9935c71
• Included in integration merge dashed/my-hermes @ 2b2bdbe9817d

Test plan

• FORK_WORKFLOW.md renders correctly on GitHub
• Branch structure and jj commands in the doc match current repo state
• Integration merge dashed/my-hermes @ 2b2bdbe9817d successfully combines this branch with main (single-file diff: FORK_WORKFLOW.md)
• "Dropping features" guide validated on 2026-04-12 rebase (dropped 2 branches cleanly)

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: exec() or eval() usage

Dynamic code execution can hide malicious behavior, especially when combined with base64 or network fetches.

Matches (first 20):

15311:+Persistent memory via the `brv` CLI — hierarchical knowledge tree with tiered retrieval (fuzzy text → LLM-driven search).
15359:+a hierarchical context tree with tiered retrieval (fuzzy text → LLM-driven
29512:+shell injection, SQL injection, path traversal, eval()/exec() with user input,
50313:+    def _start_modal_exec(self, prepared: PreparedModalExec) -> ModalExecStart:
50362:+    def _poll_modal_exec(self, handle: _ManagedModalExecHandle) -> dict | None:
50389:+    def _cancel_modal_exec(self, handle: _ManagedModalExecHandle) -> None:
50390:+        self._cancel_exec(handle.exec_id)
50489:+    def _cancel_exec(self, exec_id: str) -> None:
50541:+Uses ``Sandbox.create()`` + ``Sandbox.exec()`` instead of the older runtime
50893:+    def _start_modal_exec(self, prepared: PreparedModalExec) -> ModalExecStart:
50959:+    def _poll_modal_exec(self, handle: _DirectModalExecHandle) -> dict | None:
50966:+    def _cancel_modal_exec(self, handle: _DirectModalExecHandle) -> None:
51073:+        prepared = self._prepare_modal_exec(
51081:+            start = self._start_modal_exec(prepared)
51100:+                    self._cancel_modal_exec(start.handle)
51106:+                result = self._poll_modal_exec(start.handle)
51115:+                    self._cancel_modal_exec(start.handle)
51126:+    def _prepare_modal_exec(
51166:+    def _start_modal_exec(self, prepared: PreparedModalExec) -> ModalExecStart:
51170:+    def _poll_modal_exec(self, handle: Any) -> dict | None:

⚠️ WARNING: Outbound network calls (POST/PUT)

Outbound POST/PUT requests in new code could be data exfiltration. Verify the destination URLs are legitimate.

Matches (first 10):

1340:+        with urllib.request.urlopen(req, timeout=15) as resp:
20272:+        resp = self._httpx.post(
53933:+    response = requests.post(base_url, json=payload, headers=headers, timeout=60)

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/memory_setup.py
hermes_cli/setup.py
skills/productivity/google-workspace/scripts/setup.py
tests/hermes_cli/test_setup.py
tests/skills/test_google_oauth_setup.py

⚠️ WARNING: marshal/pickle/compile usage

These can deserialize or construct executable code objects.

Matches:

29513:+pickle.loads(), obfuscated commands.

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: base64 encoding/decoding detected

Base64 has legitimate uses (images, JWT, etc.) but is also commonly used to obfuscate malicious payloads. Verify the usage is appropriate.

Matches (first 20):

69522:+    encoded = base64.b64encode(content.encode("utf-8")).decode("ascii")
69648:+                encoded_result = base64.b64encode(

⚠️ WARNING: exec() or eval() usage

Dynamic code execution can hide malicious behavior, especially when combined with base64 or network fetches.

Matches (first 20):

69083:+        return _browser_eval(expression, task_id)
69093:+def _browser_eval(expression: str, task_id: Optional[str] = None) -> str:
69096:+        return _camofox_eval(expression, task_id)
69133:+def _camofox_eval(expression: str, task_id: Optional[str] = None) -> str:

⚠️ WARNING: Outbound network calls (POST/PUT)

Outbound POST/PUT requests in new code could be data exfiltration. Verify the destination URLs are legitimate.

Matches (first 10):

14953:+        with urllib.request.urlopen(req, timeout=timeout) as resp:
20922:+        resp = requests.post(url, files={"file": (filename, io.BytesIO(data), mime_type)}, data=fields, headers=headers, timeout=30)
21939:+        with urllib.request.urlopen(req, timeout=self._timeout + 3):
68355:+        with patch("tools.osv_check.urllib.request.urlopen", side_effect=ConnectionError("timeout")):
68811:+        response = requests.post(
71702:+    with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp:
74013:+content = urllib.request.urlopen(req, timeout=30).read().decode()
74113:+data = json.loads(urllib.request.urlopen(url, timeout=30).read())
74374:+        resp = httpx.post(f"{MEMORY_API}/recall", json={
76834:+        resp = httpx.post(f"{MEMORY_API}/recall", json={

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/memory_setup.py
hermes_cli/setup.py
skills/productivity/google-workspace/scripts/setup.py

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

[dashed]

Rebased onto upstream main @ 0d0d27d (2026-04-12). Mechanical docs-only rebase, no conflicts. New head: 24b05166.

[dashed]

Refreshed PR body after FORK_WORKFLOW.md content update on 2026-04-12:

• docs/fork-workflow: 24b05166 → d9935c71
• dashed/my-hermes: f50b94001aa5 → 2b2bdbe9817d

Branch force-pushed via jj git push --tracked. Content changes: dropped stale references to absorbed feature branches (fix/slack-mrkdwn-formatting, fix/container-systemctl-status, docs/slack-messages-tab-setup) from Branch Structure / DAG / Branch Descriptions, updated "Adding/Removing a Feature" examples to match current state, and added a new "Dropping a Branch Absorbed or Superseded Upstream" section documenting the workflow.

[github-actions]

🚨 CRITICAL Supply Chain Risk Detected

This PR contains a pattern that has been used in real supply chain attacks. A maintainer must review the flagged code carefully before merging.

🚨 CRITICAL: Install-hook file added or modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py
skills/productivity/google-workspace/scripts/setup.py

---

Scanner only fires on high-signal indicators: .pth files, base64+exec/eval combos, subprocess with encoded commands, or install-hook files. Low-signal warnings were removed intentionally — if you're seeing this comment, the finding is worth inspecting.

[github-actions]

🚨 CRITICAL Supply Chain Risk Detected

This PR contains a pattern that has been used in real supply chain attacks. A maintainer must review the flagged code carefully before merging.

🚨 CRITICAL: Install-hook file added or modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py
skills/productivity/google-workspace/scripts/setup.py

---

Scanner only fires on high-signal indicators: .pth files, base64+exec/eval combos, subprocess with encoded commands, or install-hook files. Low-signal warnings were removed intentionally — if you're seeing this comment, the finding is worth inspecting.

[github-actions]

🔎 Lint report: docs/fork-workflow vs origin/main

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 9519 on HEAD, 9519 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 5015 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.

[github-actions]

🚨 CRITICAL Supply Chain Risk Detected

This PR contains a pattern that has been used in real supply chain attacks. A maintainer must review the flagged code carefully before merging.

🚨 CRITICAL: Install-hook file added or modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py
setup.py
skills/productivity/google-workspace/scripts/setup.py

---

Scanner only fires on high-signal indicators: .pth files, base64+exec/eval combos, subprocess with encoded commands, or install-hook files. Low-signal warnings were removed intentionally — if you're seeing this comment, the finding is worth inspecting.