Skip to content

Commit 3b3955d

Browse files
committed
docs(skill): add cbm-fork-management for our copy
How we land changes in our copy first, adopt upstream items, send a change upstream by its rules, and validate in short runs. Signed-off-by: chidev <[email protected]>
1 parent f248c7e commit 3b3955d

1 file changed

Lines changed: 100 additions & 0 deletions

File tree

  • .claude/skills/cbm-fork-management
Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
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

Comments
 (0)