docs/scripts: enforce single-repo policy and +rb build-metadata suffix

- Update AGENTS.md single-repo rule to explicitly forbid creating any new Gitea repositories and to require deleting per-component repos. - Change version suffix policy from pre-release -rb to build-metadata +rb in AGENTS.md, sync-versions.sh, apply-rb-suffix.sh, verify-fork-versions.sh. - Update migration instructions to push to existing submodule/<component> branches inside RedBear-OS, not create new repos. - Update BUILD-SYSTEM-IMPROVEMENTS.md and SLEEP-IMPLEMENTATION-PLAN.md to reference submodule/* branches instead of defunct per-component repos. - Fix delete-per-component-repos.sh example to use a real historical repo.
2026-07-05 22:50:33 +03:00
parent 73cf268273
commit 54de45d461
7 changed files with 88 additions and 77 deletions
@@ -81,7 +81,16 @@ inside `RedBear-OS` either as:
  OR
 - **Tracked trees under `local/sources/<component>/`** — full source
  snapshots committed directly to the `RedBear-OS` repo as ordinary
-  files, versioned by Red Bear commits (not by external git history).
+  files, versioned by Red Bear commits (not by external git history),
+  OR
+- **Local recipes under `local/recipes/<category>/<name>/source/`** —
+  original Red Bear projects (tlc, redbear-*, cub, etc.) with no upstream
+  outside this repo.
+
+**WE DO NOT CREATE NEW REPOSITORIES.** If a component needs a Red Bear
+fork and does not already have a `submodule/<component>` branch, adding
+one is an **operator-only** decision. Agents **MUST NOT** create new
+branches or new repos on their own.

 Operators and agents **MUST NOT**:

@@ -95,12 +104,14 @@ If a recipe's `[source]` section currently points at a separate repo
 URL (e.g. `https://gitea.redbearos.org/vasilito/redbear-os-base`),
 that URL is **deprecated and must be migrated**:

-1. Create or reuse a branch inside `RedBear-OS` named
-   `submodule/<component>` (e.g. `submodule/relibc`).
-2. Push the component's source tree to that branch.
+1. Push the component's source tree to the existing `submodule/<component>`
+   branch inside `RedBear-OS`.
+2. Update the submodule's local `.git/config` origin to
+   `https://gitea.redbearos.org/vasilito/RedBear-OS.git`.
 3. Replace the recipe's `git = "..."` URL with the in-repo submodule
-   path, and add a `[submodule]` entry referencing the new branch.
-4. Update `local/AGENTS.md` and any other references.
+   path, and ensure `.gitmodules` references `branch = submodule/<component>`.
+4. Delete the per-component repository on Gitea.
+5. Update `local/AGENTS.md` and any other references.

 **Enforcement.** The cookbook's fetch/validation path treats any
 component source fetched from outside `RedBear-OS` as a misconfiguration.
@@ -137,8 +148,8 @@ Agents **MUST NOT**:
 - `git checkout -b <anything>` — no new branches, no exceptions.
 - `git push origin HEAD:refs/heads/<new-branch>` — no pushing new branches.
 - create a branch named after a version (e.g. `redoxfs-0.9.0-rb1`) — this is
-  a **policy violation**. The `-rbN` suffix lives in `Cargo.toml` version
-  fields, not in branch names.
+  a **policy violation**. Version metadata lives in `Cargo.toml` version
+  fields (as `+rbN` build metadata), not in branch names.
 - create a branch named `submodule/<new-component>` unless the operator has
  explicitly decided to fork a new upstream component.

@@ -234,31 +245,29 @@ The migration was performed with the helper scripts in `local/scripts/`:
 | `local/scripts/redirect-to-submodules.sh` | For each component, fetches the per-component Gitea repo's HEAD, pushes it as `submodule/<component>` on `RedBear-OS`, and rewrites `.gitmodules` to point at the new branch. Idempotent. Empty source repos are skipped. |
 | `local/scripts/delete-per-component-repos.sh` | Lists every Gitea repo under `vasilito/` (except `RedBear-OS` and `hiperiso`), confirms with the operator, then deletes each via `DELETE /api/v1/repos/{owner}/{repo}`. |

-**To re-run for a future component** (e.g. a new per-component repo that
-someone accidentally creates):
+**To re-run for a future component** (if a per-component repo was accidentally
+created or inherited):

-1. Verify the per-component repo is a Red Bear component, not unrelated.
+1. Verify the component belongs in `RedBear-OS`.
 2. `export REDBEAR_GITEA_TOKEN=...` (or set up `~/.netrc`).
-3. Push the working-tree HEAD as a branch:
+3. Push the working-tree HEAD to the correct `submodule/<component>` branch:
   ```bash
   cd local/sources/<component>
-   git push https://${REDBEAR_GITEA_TOKEN}@gitea.redbearos.org/vasilito/RedBear-OS.git \
-     HEAD:refs/heads/submodule/<component>
+   git remote set-url origin https://gitea.redbearos.org/vasilito/RedBear-OS.git
+   git push -u origin master:refs/heads/submodule/<component>
   ```
-4. Declare it in `.gitmodules` (copy an existing entry, change the name + branch).
-5. `./local/scripts/delete-per-component-repos.sh` to remove the orphaned repo.
+4. Delete the per-component repository on Gitea.
+5. Verify with:
+   ```bash
+   # Should print only: hiperiso, RedBear-OS
+   curl -fsS -H "Authorization: token $REDBEAR_GITEA_TOKEN" \
+     'https://gitea.redbearos.org/api/v1/users/vasilito/repos?limit=200' \
+     | jq -r '.[].name' | sort

-**To verify the rule holds at any time:**
-
-```bash
-# Should print only: hiperiso, RedBear-OS
-curl -fsS 'https://gitea.redbearos.org/api/v1/users/vasilito/repos?limit=200' \
-  | jq -r '.[].name' | sort
-
-# Should print zero matches (CHANGELOG.md historical entries are exempt)
-grep -rn 'gitea.redbearos.org/vasilito/redbear-os-' . --include='*.md' \
-  | grep -v 'CHANGELOG.md'
-```
+   # Should print zero matches (CHANGELOG.md historical entries are exempt)
+   grep -rn 'gitea.redbearos.org/vasilito/redbear-os-' . --include='*.md' \
+     | grep -v 'CHANGELOG.md'
+   ```

 ### Connection details

@@ -506,24 +506,20 @@ local-fork source tree.

 **Problem.** `local/sources/base/` is a nested git repo (the
 local-fork model) with `origin = https://gitlab.redox-os.org/redox-os/base.git`.
-**Resolved 2026-07-01:** the Red Bear-specific per-component fork at
-`vasilito/redbear-os-base` has been migrated to the `submodule/base`
-branch inside the canonical `RedBear-OS` repo per the SINGLE-REPO RULE
-(see `local/AGENTS.md`). The base component now lives only as the
-`submodule/base` branch on `RedBear-OS`. A Red Bear developer who
+**Resolved 2026-07-01:** the base component has been migrated to the
+`submodule/base` branch inside the canonical `RedBear-OS` repo per the
+SINGLE-REPO RULE (see `local/AGENTS.md`). The base component now lives only as
+the `submodule/base` branch on `RedBear-OS`. A Red Bear developer who
 commits inside `local/sources/base/` and runs `git push origin master`
-would push Red Bear fork commits **to upstream Redox**, where they
-will be rejected (or worse, silently fail).
+pushes to the `submodule/base` branch of `RedBear-OS`.

-**Current behavior.** Most Red Bear base commits are made by the
-`Red Bear OS <build@redbearos.org>` author bot during automated syncs, which
-push to a different fork URL configured out-of-band. The inner-repo
-`origin` is therefore orphaned from normal operator workflows.
+**Current behavior.** All 9 declared submodules now point to
+`https://gitea.redbearos.org/vasilito/RedBear-OS.git` on their
+`submodule/<component>` branch. The per-component repo era is over.

-**Proposal.** Set the inner `local/sources/base/` origin to Red Bear's gitea
-URL via `local/scripts/sync-fork-remotes.sh` (new file). Same treatment for
-`local/sources/{relibc,kernel,bootloader,installer,redoxfs,userutils}` if any
-of them have the same issue.
+**Proposal.** Keep `local/scripts/sync-fork-remotes.sh` (or equivalent
+maintenance) so that no submodule's `origin` drifts back to upstream Redox
+or to an old per-component repo URL.

 **Expected gain.** Eliminates a footgun. Operators can commit + push from
 inside the local fork and reach the right remote.
@@ -300,8 +300,7 @@ the `recovered/quirks` branch in the outer RedBear-OS repo):
  - `4191b8543` — base submodule pointer (acpid AML sequence)
  - `850124559` — kernel submodule pointer (s2idle kstop handler)

- **Red Bear OS inner** commits (historical — these repos have since been
-  merged as `submodule/base` and `submodule/kernel` branches inside the
-  canonical `RedBear-OS` repo per the SINGLE-REPO RULE):
-  - `redbear-os-base 5d2d114` — acpid: full Linux AML S-state sequence
-  - `redbear-os-kernel 75c7618` — kernel: s2idle / s3 kstop handler
+- **Red Bear OS inner** commits (historical — now found on `submodule/base`
+  and `submodule/kernel` branches inside the canonical `RedBear-OS` repo):
+  - `submodule/base 5d2d114` — acpid: full Linux AML S-state sequence
+  - `submodule/kernel 75c7618` — kernel: s2idle / s3 kstop handler
@@ -1,21 +1,21 @@
 #!/usr/bin/env bash
-# apply-rb-suffix.sh — Apply the -rb<branch> version suffix to all Cat 2 forks.
+# apply-rb-suffix.sh — Apply the +rb<branch> version build-metadata suffix to all Cat 2 forks.
 #
 # This script is now a thin wrapper around sync-versions.sh Phase 2.
 # It exists for backward compatibility and focused Cat-2-only operation.
 #
 # Policy (local/AGENTS.md § "Version conventions"):
 #
-#   Every Cat 2 fork version MUST be `<upstream-version>-rb<branch-version>` where:
+#   Every Cat 2 fork version MUST be `<upstream-version>+rb<branch-version>` where:
 #     <upstream-version> = the upstream version the fork currently tracks
 #     <branch-version>   = the current Red Bear OS git branch (e.g. 0.2.5)
 #
-#   The `-rb<branch>` suffix is a Cargo pre-release identifier. Per SemVer, a
-#   pre-release version (e.g. 0.9.0-rb0.2.5) is NEVER substituted for the
-#   corresponding stable version (0.9.0).
+#   The `+rb<branch>` suffix is Cargo build metadata. It does NOT affect
+#   SemVer precedence and allows transitive crates.io deps requiring
+#   `^X.Y.Z` to resolve to the local fork via [patch.crates-io].
 #
 # Usage:
-#   ./local/scripts/apply-rb-suffix.sh           # Apply -rb<branch> to all
+#   ./local/scripts/apply-rb-suffix.sh           # Apply +rb<branch> to all
 #   ./local/scripts/apply-rb-suffix.sh --check   # Verify only
 #   ./local/scripts/apply-rb-suffix.sh --rollback # Revert to stable X.Y.Z
 #
@@ -55,11 +55,11 @@ if [[ -z "$BRANCH_VERSION" ]]; then
    exit 1
 fi

-RB_SUFFIX="-rb${BRANCH_VERSION}"
+RB_SUFFIX="+rb${BRANCH_VERSION}"

-# ---- Rollback mode: strip all -rb<x.y.z> suffixes ----
+# ---- Rollback mode: strip all +rb<x.y.z> suffixes ----
 if [[ $ROLLBACK -eq 1 ]]; then
-    echo "=== Rolling back Cat 2 forks to stable versions (stripping -rb*) ==="
+    echo "=== Rolling back Cat 2 forks to stable versions (stripping +rb*) ==="
    for fork_dir in local/sources/*/; do
        [ -d "$fork_dir" ] || continue
        fork_name=$(basename "$fork_dir")
@@ -70,8 +70,8 @@ if [[ $ROLLBACK -eq 1 ]]; then
        fi
        current="$(grep -E '^version\s*=' "$f" | head -1 | sed 's/.*"\(.*\)".*/\1/' || true)"
        [[ -n "$current" ]] || continue
-        if [[ "$current" == *"-rb"* ]]; then
-    base="$(echo "$current" | sed -E 's/-rb([0-9]+(\.[0-9]+\.[0-9]+)?)$//')"
+        if [[ "$current" == *"+rb"* ]]; then
+            base="$(echo "$current" | sed -E 's/\+rb([0-9]+(\.[0-9]+\.[0-9]+)?)$//')"
            sed -i "s|^version = \"${current}\"|version = \"${base}\"|" "$f"
            echo "  ROLLBACK: $fork_name $current → $base"
        fi
@@ -113,7 +113,7 @@ for fork in "${CAT2_FORKS[@]}"; do
    current="$(grep -E '^version\s*=' "$f" | head -1 | sed 's/.*"\(.*\)".*/\1/' || true)"
    [[ -n "$current" ]] || { echo "  SKIP ${fork}: empty version"; continue; }

-    base="$(echo "$current" | sed -E 's/(-rb[0-9]+(\.[0-9]+\.[0-9]+)?)+$//')"
+    base="$(echo "$current" | sed -E 's/(\+rb[0-9]+(\.[0-9]+\.[0-9]+)?)+$//')"
    target="${base}${RB_SUFFIX}"

    if [[ "$current" == "$target" ]]; then
@@ -149,6 +149,6 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 if [ -x "$SCRIPT_DIR/verify-fork-versions.sh" ]; then
    if ! "$SCRIPT_DIR/verify-fork-versions.sh" 2>&1 | grep -q "^All Cat 2 forks pass"; then
        echo "WARNING: verify-fork-versions.sh found content mismatches." >&2
-        echo "         The -rb suffix is applied but some forks may not match upstream." >&2
+        echo "         The +rb suffix is applied but some forks may not match upstream." >&2
    fi
 fi
@@ -10,7 +10,7 @@
 #   ./local/scripts/delete-per-component-repos.sh            # interactive
 #   ./local/scripts/delete-per-component-repos.sh --dry-run  # list only
 #   ./local/scripts/delete-per-component-repos.sh --yes      # no prompts
-#   ./local/scripts/delete-per-component-repos.sh --only redbear-os-base,redox-drm
+#   ./local/scripts/delete-per-component-repos.sh --only redbear-os-base
 #   ./local/scripts/delete-per-component-repos.sh -h         # this help

 set -euo pipefail
@@ -8,7 +8,10 @@
 #           version = "<branch>"  (e.g. "0.2.5")
 #
 #   Cat 2 — Upstream Redox forks (local/sources/*/):
-#           version = "<upstream-base>-rb<branch>"  (e.g. "0.9.0-rb0.2.5")
+#           version = "<upstream-base>+rb<branch>"  (e.g. "0.9.0+rb0.2.5")
+#
+# The `+rb` suffix is Cargo build metadata, not a pre-release identifier.
+# Using `-rb` is a policy violation.
 #
 # When the branch changes (e.g. 0.2.5 → 0.2.6), running this script bumps
 # Cat 1 versions to the new branch version AND updates Cat 2 suffixes to
@@ -47,7 +50,7 @@ if [[ -z "$TARGET_VERSION" ]]; then
 fi

 echo "Target version: $TARGET_VERSION (from branch '$BRANCH')"
-echo "Cat 2 suffix:   -rb$TARGET_VERSION"
+echo "Cat 2 suffix:   +rb$TARGET_VERSION"
 echo ""

 # ---- Exclusions ----
@@ -80,9 +83,9 @@ should_exclude() {
 }

 # ---- Helper: extract upstream base from a Cat 2 version ----
-# Strips any existing -rb<x.y.z> suffix to get the upstream base version.
+# Strips any existing +rb<x.y.z> build-metadata suffix to get the upstream base version.
 strip_rb_suffix() {
-    echo "$1" | sed -E 's/(-rb[0-9]+(\.[0-9]+\.[0-9]+)?)+$//'
+    echo "$1" | sed -E 's/(\+rb[0-9]+(\.[0-9]+\.[0-9]+)?)+$//'
 }

 # ---- Phase 1: Cat 1 — In-house crates (local/recipes/*/source/) ----
@@ -149,7 +152,7 @@ CAT2_CHANGED=0
 CAT2_CHECKED=0
 CAT2_DRIFT=0

-RB_SUFFIX="-rb${TARGET_VERSION}"
+RB_SUFFIX="+rb${TARGET_VERSION}"

 update_cat2_version() {
    local f="$1"
@@ -163,7 +166,7 @@ update_cat2_version() {
    current="$(grep -E '^version\s*=' "$f" | head -1 | sed 's/.*"\(.*\)".*/\1/' || true)"
    [[ -n "$current" ]] || return 0

-    # Strip any existing -rb<x.y.z> suffix to get upstream base
+    # Strip any existing +rb<x.y.z> build-metadata suffix to get upstream base
    base="$(strip_rb_suffix "$current")"
    target="${base}${RB_SUFFIX}"

@@ -2,13 +2,17 @@
 # verify-fork-versions.sh — Enforce the "no fake version label" rule.
 #
 # For each local Cat 2 fork under local/sources/<name>/ that has a
-# version field of the form `<X.Y.Z>-rb<B.B.B>`, verify that:
+# version field of the form `<X.Y.Z>+rb<B.B.B>`, verify that:
 #   1. The fork's source content is a real rebase onto the matching
 #      upstream `<X.Y.Z>` release (with the Red Bear patches applied).
 #   2. The `<B.B.B>` part matches the current Red Bear OS git branch.
 #   3. The `version` field in the fork's Cargo.toml starts with that
 #      upstream release tag.
 #
+# The `+rb` suffix is Cargo build metadata, NOT a pre-release identifier.
+# Using `-rb` is a policy violation because Cargo treats it as a pre-release
+# and transitive deps requiring `^X.Y.Z` will not resolve to the fork.
+#
 # This script is invoked by build-preflight.sh and apply-rb-suffix.sh.
 # It returns exit code 1 if any fork fails the check.

@@ -38,18 +42,18 @@ for fork_dir in local/sources/*/; do
    version=$(grep -E '^version\s*=' "$toml" | head -1 | sed -E 's/.*"([^"]+)".*/\1/') || true
    [ -n "$version" ] || continue

-    # Only check Cat 2 forks (those with -rb suffix)
-    if [[ "$version" != *"-rb"* ]]; then
+    # Only check Cat 2 forks (those with +rb build-metadata suffix)
+    if [[ "$version" != *"+rb"* ]]; then
        continue
    fi

-    # Extract the upstream base version (before -rb) and the branch version (after -rb)
-    base_version=$(echo "$version" | sed -E 's/-rb[0-9]+\.[0-9]+\.[0-9]+$//') || true
-    rb_branch=$(echo "$version" | sed -E 's/^.*-rb([0-9]+\.[0-9]+\.[0-9]+)$/\1/') || true
+    # Extract the upstream base version (before +rb) and the branch version (after +rb)
+    base_version=$(echo "$version" | sed -E 's/\+rb[0-9]+\.[0-9]+\.[0-9]+$//') || true
+    rb_branch=$(echo "$version" | sed -E 's/^.*\+rb([0-9]+\.[0-9]+\.[0-9]+)$/\1/') || true

    if [ -z "$base_version" ] || [ -z "$rb_branch" ]; then
        echo "ERROR: $toml has malformed version '$version'" >&2
-        echo "       Expected format: <X.Y.Z>-rb<B.B.B> (e.g. 0.9.0-rb0.2.5)" >&2
+        echo "       Expected format: <X.Y.Z>+rb<B.B.B> (e.g. 0.9.0+rb0.2.5)" >&2
        violations=$((violations + 1))
        continue
    fi
@@ -79,10 +83,10 @@ for fork_dir in local/sources/*/; do
        continue
    fi

-    # Verify the -rb suffix matches the current branch
+    # Verify the +rb suffix matches the current branch
    if [ -n "$BRANCH_VERSION" ] && [ "$rb_branch" != "$BRANCH_VERSION" ]; then
-        echo "ERROR: $fork_name version suffix -rb$rb_branch does not match" >&2
-        echo "       current branch '$BRANCH' (expected -rb$BRANCH_VERSION)." >&2
+        echo "ERROR: $fork_name version suffix +rb$rb_branch does not match" >&2
+        echo "       current branch '$BRANCH' (expected +rb$BRANCH_VERSION)." >&2
        violations=$((violations + 1))
        continue
    fi