|
| 1 | +--- |
| 2 | +name: cbm-fork-management |
| 3 | +description: Use when changing our copy of codebase-memory-mcp (the lev branch on lev-os), landing a fix there, adopting an upstream issue or pull request, sending a change upstream, pulling upstream main in, or validating a change. Selectors: --status, --land, --update-from-prs, --contribute, --sync-upstream, --validate. |
| 4 | +--- |
| 5 | + |
| 6 | +# cbm-fork-management |
| 7 | + |
| 8 | +Our copy lives first. Upstream is a courtesy that follows its own rules. Validation is many short runs, never one long one. |
| 9 | + |
| 10 | +## Facts |
| 11 | + |
| 12 | +| Thing | Value | |
| 13 | +|---|---| |
| 14 | +| Upstream | `DeusData/codebase-memory-mcp`, remote `origin`, branch `main`. Only @DeusData merges and speaks for the project. | |
| 15 | +| Our copy | `lev-os/codebase-memory-mcp`, remote `lev-os`, integration branch `lev`. | |
| 16 | +| Work branches | `fix/<topic>`, `np/<topic>`, `carry/<upstream number>-<topic>`, in `.worktrees/<name>` inside this repository. | |
| 17 | +| This skill, fast-build tools, any build or CI config we change | `lev` only. Never in a branch that goes upstream. | |
| 18 | + |
| 19 | +Confirm the remotes with `git remote -v` before any push. Never rebase, stash, or `git add -A`. Stage named paths only. |
| 20 | + |
| 21 | +## Rules (JP, 2026-11-13) |
| 22 | + |
| 23 | +1. **Land in our copy at once.** A change that passed its checks and a review merges into `lev` the same day. It never waits for an upstream merge. |
| 24 | +2. **Upstream only on request, and by the book.** Send a change upstream when the maintainer asked for it or JP said yes. Then follow `CONTRIBUTING.md` on `origin/main` to the letter; re-read it each time. |
| 25 | +3. **Adopt what we agree with.** Open upstream issues and pull requests that fix a fault we measure get carried into `lev` and tested here, with or without an upstream merge. |
| 26 | +4. **Fork-only means fork-only.** Anything that changes build config, CI, scripts or agent files for our own speed stays on `lev`. |
| 27 | +5. **No prayer runs.** A run longer than 10 minutes starts only after runs of 1, 2 and 5 minutes passed on the same tree. |
| 28 | + |
| 29 | +## --status |
| 30 | + |
| 31 | +Print one table, then stop: |
| 32 | + |
| 33 | +- `lev` against `lev-os/lev` and against `origin/main` (ahead, behind). |
| 34 | +- Each work branch: merged into `lev` or not, pushed or not, checks run. |
| 35 | +- Each open upstream pull request of ours: head, checks, last maintainer comment, what it waits for. |
| 36 | +- Carried upstream items not yet merged upstream. |
| 37 | + |
| 38 | +## --validate (the ladder) |
| 39 | + |
| 40 | +The upstream test build compiles every source in one compiler command: one changed line costs about 15 minutes. Do not use it to iterate. |
| 41 | + |
| 42 | +| Step | Budget | What | |
| 43 | +|---|---|---| |
| 44 | +| 1 | 1 min | Rebuild only changed files into objects, link, run the one test: `CBM_TEST_ONLY=<suite>:<test> <runner> <suite>`. | |
| 45 | +| 2 | 2 min | Red proof: same test with the fix removed must fail. Swap the one production file, rebuild that object, swap back, confirm with `cmp`. | |
| 46 | +| 3 | 5 min | The suites that cover the changed files. | |
| 47 | +| 4 | 10 min | Neighbour suites, each as its own process, in parallel within the machine's load limit. | |
| 48 | +| 5 | long | The wide run, once, at the final commit, only after 1 to 4 pass. Split it so no part exceeds a tool time limit. | |
| 49 | + |
| 50 | +- Each step writes a log and a one-line result. A claim in a pull request cites a log that exists. |
| 51 | +- Use a short private runtime folder under `/tmp` (socket paths hold 103 bytes on macOS) and a private cache folder. |
| 52 | +- If a step exceeds its budget, stop and find out why before starting the next one. |
| 53 | +- A reviewer that only reads cannot settle a run claim. The owner reruns every program check and every planted fault once at the final commit. |
| 54 | + |
| 55 | +## --land `<branch>` |
| 56 | + |
| 57 | +1. Checks: ladder steps 1 to 4 pass on the branch head. |
| 58 | +2. Review: a fresh reader on another model reads the diff with a rubric the maker never saw. Blockers are repaired, then read again. Never approve your own work. |
| 59 | +3. Merge into `lev`: `git merge --no-ff -s <branch>` with subject `Merge <branch>: <one plain sentence of what now works>`. |
| 60 | +4. Ladder step 3 on the merged tree, then `git push lev-os lev`. |
| 61 | +5. Record what landed and what it measured in the project's ledger. |
| 62 | + |
| 63 | +A branch that also goes upstream is cut from `origin/main`, so merging it into `lev` may conflict. Resolve in the merge commit; never rewrite the branch. |
| 64 | + |
| 65 | +## --update-from-prs |
| 66 | + |
| 67 | +1. List candidates: `gh issue list` and `gh pr list` on upstream, open, sorted by recent activity, filtered to the languages and passes we measure. |
| 68 | +2. For each candidate, decide **adopt**, **watch** or **skip** with one line of reason. Adopt needs a fault we can reproduce or measure here. |
| 69 | +3. Adopt: branch `carry/<number>-<topic>` from `lev`, cherry-pick the author's commits with authorship and sign-off kept, add a failing-first test if the item has none. |
| 70 | +4. Run `--validate`, then `--land`. |
| 71 | +5. Keep a carry table (upstream number, our branch, landed commit, upstream state). When upstream merges the item, drop our carry at the next `--sync-upstream`. |
| 72 | + |
| 73 | +Do not comment on another person's upstream pull request unless JP says so. |
| 74 | + |
| 75 | +## --contribute `<branch>` |
| 76 | + |
| 77 | +Only when rule 2 holds. Before the push, every line here is true: |
| 78 | + |
| 79 | +- A tracking issue exists and the pull request references it (`Fixes #N`, or say plainly why it does not close it). |
| 80 | +- One issue for each pull request. Under 500 changed lines. C only. No fork-only file in the diff. |
| 81 | +- The branch is cut from current `origin/main`. Merge main in; never rebase a pushed branch. |
| 82 | +- Every commit has a `Signed-off-by` that matches its author: `scripts/check-dco.sh origin/main..HEAD` passes. Another person's commit keeps their authorship and sign-off. |
| 83 | +- Conventional subjects. No attribution trailer, no process trailer, no link to a chat or agent session, no wording about our private setup. |
| 84 | +- The first line of the pull request text discloses the AI agent and names the accountable person. |
| 85 | +- Every claim is checkable: the failing test on main, the command, the counts, the machine. Each number comes from a log of the final commit. |
| 86 | +- Known limits are named. What was not run locally is named. |
| 87 | +- Format: the project formats `src/` and headers only. Never reformat test files whole. |
| 88 | +- The branch already landed in `lev` (rule 1), and a fresh reviewer read the final commit before the push, not after. |
| 89 | + |
| 90 | +After opening or pushing: link the pull request in the session, then report its checks. A maintainer request becomes a new `--land` then `--contribute` round. Do not open a second pull request for a fix the maintainer did not ask to see apart. |
| 91 | + |
| 92 | +## --sync-upstream |
| 93 | + |
| 94 | +1. `git fetch origin`, then `git merge --no-ff -s origin/main` into `lev` on a work branch first. |
| 95 | +2. Conflicts: read both sides and keep both meanings. A new upstream field or flag must be set by our code paths too. |
| 96 | +3. Drop carries that upstream merged. Run `--validate` steps 3 to 5, then `--land`. |
| 97 | + |
| 98 | +## Stop and ask JP |
| 99 | + |
| 100 | +A new upstream pull request or comment that the maintainer did not ask for; closing an upstream item; anything from a private code base in a fixture, commit or public text; a release of our build to other people. |
0 commit comments