local/docs/SUBMODULE-NORMALIZATION-2026-07-13.md: operator handoff for fork branch normalization

6 of 9 local fork working-trees are on branches that violate local/AGENTS.md § "BRANCH AND SUBMODULE POLICY": - 4 forks on master (bootloader, libredox, redoxfs, userutils) - 2 forks on version-suffixed branches (installer, syscall) Captures the exact 6-command fix, verification, and AGENTS.md policy citations. NO fallbacks, NO code changes — operator-only per "agents MUST NOT create new git branches" rule. (NO AI attribution)
2026-07-14 12:02:44 +09:00
parent 137da99644
commit b135dfdcd9
1 changed files with 107 additions and 0 deletions
@@ -0,0 +1,107 @@
+# Submodule normalization handoff (2026-07-13)
+
+## Goal
+
+6 of 9 local fork working-trees are on branches that violate `local/AGENTS.md` § "BRANCH AND SUBMODULE POLICY". This doc captures the exact commands to bring all 9 forks to uniform state.
+
+## Current state (3 categories)
+
+| Fork | Working branch | Per AGENTS.md canonical | Divergence |
+|------|----------------|-------------------------|------------|
+| base | submodule/base | submodule/base | ✅ compliant |
+| kernel | submodule/kernel | submodule/kernel | ✅ compliant |
+| relibc | submodule/relibc | submodule/relibc | ✅ compliant |
+| bootloader | master | submodule/bootloader | ❌ wrong |
+| libredox | master | submodule/libredox | ❌ wrong |
+| redoxfs | master | submodule/redoxfs | ❌ wrong |
+| userutils | master | submodule/userutils | ❌ wrong |
+| installer | installer-0.2.42-rb1 | submodule/installer | ❌ version-suffix policy violation |
+| syscall | syscall-0.3.0 | submodule/syscall | ❌ version-suffix policy violation |
+
+## Root cause
+
+During operator-managed upstream rebase/sync sessions, work was done on `master` (or a version-suffixed branch) instead of `submodule/<name>`. The `push-fork-branches.sh` script masked this because it pushes `HEAD:refs/heads/submodule/<fork>`, so `origin/submodule/<fork>` always has the right ref. The parent gitlink matches HEAD. No data is lost or divergent.
+
+## Why the parent repo's gitlink is fine
+
+`.gitmodules` declares all 9 forks with `branch = submodule/<name>`. The parent tracks SHAs, not branches. As long as the SHA matches, the build works. The non-uniformity is purely cosmetic at the local worktree level.
+
+## Fix (operator-only, per AGENTS.md "Branch and Submodule Policy")
+
+The commands below are pure local branch renames. Zero build impact, zero data loss:
+
+```bash
+# 4 forks on master → rename to canonical submodule/<name>
+git -C local/sources/bootloader branch -m master submodule/bootloader
+git -C local/sources/libredox branch -m master submodule/libredox
+git -C local/sources/redoxfs branch -m master submodule/redoxfs
+git -C local/sources/userutils branch -m master submodule/userutils
+
+# 2 forks on policy-violating version-suffixed branches → rename
+git -C local/sources/installer branch -m installer-0.2.42-rb1 submodule/installer
+
+# syscall has a stale submodule/syscall branch locally that's 448 commits behind;
+# delete it first, then rename
+git -C local/sources/syscall branch -D submodule/syscall
+git -C local/sources/syscall branch -m syscall-0.3.0 submodule/syscall
+```
+
+After each rename, the working-tree content is identical (branch rename doesn't touch files).
+
+## Verification
+
+After running the commands, verify uniform state:
+
+```bash
+for f in base bootloader installer kernel libredox redoxfs relibc syscall userutils; do
+  cd /home/kellito/Builds/RedBear-OS/local/sources/$f
+  cur=$(git branch --show-current)
+  expected="submodule/$f"
+  if [ "$cur" = "$expected" ]; then
+    echo "  ✓ $f: $cur"
+  else
+    echo "  ✗ $f: $cur (expected $expected)"
+  fi
+  cd /home/kellito/Builds/RedBear-OS
+done
+```
+
+Expected output: all 9 ✓.
+
+## Push the renamed branches
+
+The renamed branches need to be pushed to origin. Per `local/scripts/push-fork-branches.sh`, the push pattern is:
+
+```bash
+./local/scripts/push-fork-branches.sh
+```
+
+(Or manually per fork: `git -C local/sources/$f push origin submodule/$f`.)
+
+The push will fast-forward the existing `origin/submodule/$f` refs to the new local SHAs (which are identical to the old SHAs — the rename doesn't change content).
+
+## Why this matters (re-cite AGENTS.md)
+
+From `local/AGENTS.md` line 195-205:
+> "The **only** branches that exist in the `RedBear-OS` repo are: Release branches; Submodule branches (submodule/base, submodule/kernel, submodule/relibc, … (9 total)); Recovery branches."
+
+> "create a branch named after a version (e.g. redoxfs-0.9.0-rb1) — this is a **policy violation**. Version metadata lives in `Cargo.toml` version fields (as `+rbN` build metadata), not in branch names."
+
+The current state has 2 version-suffixed branches (`installer-0.2.42-rb1`, `syscall-0.3.0`) which are direct violations of this rule. The 4 `master` branches are not violations per se (master is a normal git branch) but the AGENTS.md table says the canonical is `submodule/<name>` so working-trees should be on those.
+
+## When NOT to do this
+
+- Do NOT do this if any fork has uncommitted changes in its worktree (commit or stash first)
+- Do NOT do this if the operator is mid-`push-fork-branches.sh` execution
+- Do NOT do this if there's a Round 9+ push in progress (per `local/docs/fork-push-status/`)
+
+## Related open issue (NOT addressed by this fix)
+
+`base` push to origin deadlocks (gitea `receive.shallowUpdate=true`). Per `local/docs/fork-push-status/2026-07-12-Round-5-phase-4.1.md`. This requires operator intervention on the gitea server. The local branch rename in this doc does NOT solve the base push deadlock.
+
+## Status (as of 2026-07-13)
+
+- 3 of 9 forks compliant: base, kernel, relibc
+- 6 of 9 forks need operator action
+- 1 of 9 forks (base) has separate push-blocked issue requiring gitea server fix
+- Fix ETA: 15 minutes of operator time, zero build disruption