From a22277cb205ca7ea751d4e28acfce53a4671111d Mon Sep 17 00:00:00 2001
From: Claude Sleep <claude@local>
Date: Wed, 13 May 2026 02:39:01 -0400
Subject: [PATCH] docs(contributing): add fork-as-lab workflow section

Add branch strategy, label conventions, issue template usage, Linear sync
flow, and upstream promotion guide. Aligns with the fork pipeline shipped
2026-05-13 (sync-upstream.yml + linear-sync.yml).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .github/CONTRIBUTING.md | 84 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index d55ce87d..2638d5f6 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -65,6 +65,90 @@ should include:
 Images should be hosted with GitHub user attachments or another external asset
 URL instead of committed to the repository.
 
+## Fork-as-Lab Workflow
+
+`Fearvox/EverOS` is a development fork of `EverMind-AI/EverOS`. All experimental
+work happens on the fork before selective promotion upstream.
+
+### Staying Current with Upstream
+
+The fork auto-rebases onto upstream `main` every 6 hours via
+`sync-upstream.yml`. This replays fork-only commits (templates, workflows, docs)
+on top of the latest upstream. If you're working on a feature branch:
+
+```bash
+# Rebase your branch onto the latest fork main
+git fetch origin
+git rebase origin/main
+```
+
+If the auto-rebase encounters a conflict, it aborts and opens a tracking issue.
+Manual resolution:
+
+```bash
+git checkout main
+git pull upstream main --rebase
+# resolve conflicts, then:
+git push origin main --force-with-lease
+```
+
+### Branch Strategy
+
+| Branch pattern | Purpose | Lifetime |
+|---------------|---------|----------|
+| `sleep-iter-*-*` | Automated overnight runs | Feature branch, merged or closed |
+| `codex-watch-*` | Codex co-agent patrol | Isolated worktree, never touch |
+| `feature/*` | Human-driven features | Feature branch → PR to origin/main |
+| `sleep-log` | Overnight run audit log | Persistent tracking branch |
+
+### Label Conventions
+
+| Label | Color | Use on |
+|-------|-------|--------|
+| `pr-mirror` | `#0E8A16` | Issues that mirror an upstream PR — triggers Linear sync |
+| `tracking` | `#5319E7` | Long-lived tracking issues |
+| `security` | `#B60205` | Security advisories or security-relevant PRs |
+| `urgent` | `#D93F0B` | High-priority; escalates in Linear |
+| `sync-failed` | `#D93F0B` | Auto-applied when Linear sync fails for an issue |
+
+### Issue Templates
+
+Use the template picker when opening an issue. The two fork-specific templates:
+
+- **PR Tracker** (`pr_tracker.yml`) — track an upstream PR for Linear/Slack
+  visibility. Requires `pr_number`, `pr_url`, `author`, `area`, `scope`, and
+  `evidence`. Applies `pr-mirror` + `tracking` labels.
+- **Security Tracker** (`security_tracker.yml`) — track a security advisory.
+  Adds `security` + `urgent` labels on top of the PR tracker labelset.
+
+Both templates auto-trigger `linear-sync.yml`, which creates a corresponding
+Linear issue in the `EverMind-Dash` project and comments back with the EVE
+identifier.
+
+### Linear Sync
+
+Issues labeled `pr-mirror` are mirrored to Linear's `EverMind-Dash` project
+automatically. The sync is one-way (GitHub → Linear). The bot comments
+`🔗 Linear: [EVE-<N>](url)` on success.
+
+If the bot adds a `sync-failed` label, check the workflow run logs at
+`https://github.com/Fearvox/EverOS/actions/workflows/linear-sync.yml`.
+
+### Promoting to Upstream
+
+When a fork change is ready for `EverMind-AI/EverOS`:
+
+```bash
+gh pr create --repo EverMind-AI/EverOS \
+  --base main \
+  --head Fearvox:main \
+  --title "feat: description" --body "..."
+```
+
+Templates and workflows committed to the fork are replayed on top of upstream
+during every rebase cycle. They never conflict unless upstream adds same-named
+files — low probability, handled by auto-rebase conflict detection.
+
 ## Style Notes
 
 - Follow existing patterns before adding new abstractions.