gitstalk docs concepts

Concepts: how a change grows

One diagram and a few short cards explain the whole model. A change is a bean, it lands on the sprout once it passes on the exact merged code, and the stalk only moves to verified work.

The life of a bean

1. Pushbean/<name>
2. Pre-land checksprout + bean, whole suite
3. LANDEDon the sprout
4. ValidationCI on the sprout
5. On the stalkstable, green

A bean is a small change on its own branch. It is checked together with the newest sprout, lands there at once if it is green, and later moves to the stable stalk when CI validates the sprout. The side exits are below.

Which concepts apply to pushed repositories today: pre-land check, validation, revert-first, informed repair and decision cards (the push prints the card id) all run. Separate acceptance tests for pushed beans do not exist yet, so the reconcile step has nothing to amend there.

The pieces, one at a time

Bean

One change, pushed as bean/<name> by an agent or a person. You never open a pull request or wait in a queue. See Git compatibility.

Sprout

The staged line. A bean lands here as soon as its pre-land check is green, and every later bean is checked on top of it. Branch: sprout.

Stalk

The stable line, and the default branch you clone. It moves only to a sprout commit that passed validation, together with the beans below it. No token, key or role can push to the sprout or the stalk: only the engine moves them. Branch: stalk.

Pre-land check

The engine merges your bean onto the current sprout and runs the whole suite on that exact merged tree, not on your branch alone. Tests that pass on your branch can still fail after the merge; this finds out before landing. Each bean in check gets its own container. See Checks.

Validation

After landing, CI runs on the sprout's newest commit. A green validation moves the stalk to that commit. That is why the History tab can show a commit as landed but not yet validated. The word green in a status ref means the same as validated. Only a limited number of landings may run ahead of validation; the exact rule is in Architecture.

Revert-first

If validation goes red, the same failure must repeat to count, so a flaky test does not undo good work. When one bean is the only suspect it is taken off the sprout at once, before other beans pile on top. Otherwise the engine resets the sprout to the stalk and re-checks the beans in the window, suspects one at a time.

Informed repair

A red goes back to its author with what failed and why, not just a red cross. Agents read it in the push output (or with bean_status over MCP), fix the bean and push again.

$ git push -o wait origin HEAD:refs/heads/bean/add-truncate
remote: gitstalk: RED: add-truncate was not landed. Merged onto the sprout, these tests failed:
remote: gitstalk:   - truncate keeps short strings unchanged
remote: gitstalk: it collided with these landed beans (accepted behaviour; keep both):
remote: gitstalk:   - fix-trim "Trim input before truncating"
remote: gitstalk:     intent: Strings are trimmed before any length check.
remote: gitstalk: fix: git fetch origin sprout && git rebase origin/sprout
remote: gitstalk:      then fix, commit and git push -f origin HEAD:refs/heads/bean/add-truncate

Reconcile

If the same test fails again, the engine looks at the landed tasks behind the failing tests. When a test only pinned an old value that another change legitimately changed, the test is updated and the bean lands. This runs in the engine today, but on pushed beans there are no separate acceptance tests to amend, so a real clash goes straight to a decision card.

Decision card beta

When two changes truly want different behaviour, the engine raises a card with both intents, and the push prints decision card D001: .... There is no answer control on a repository's web pages yet (it exists only in the admin race view). Today the engine answers by itself after 30 seconds: the landed bean's behaviour stays, and the new bean goes back to its author with that decision. If it is still red against the winner after that, it is parked as needs a person: two specs disagree.

Approval rules beta

A .gitstalk/policy.yml file can say which kinds of change land on their own and which wait for a person. A triaged bean is also compared with the beans it never saw (landed after it forked, or pushed before it and still in flight); when their intents clash, it goes back to its author to recheck rather than to a person. See Approval rules.

Clef and Jev

Clef (from Cloudflare) and Jev (from TypeSafe) are small decision models on Workers AI. They only pick or rank: choose a route, order a list, decide which view answers a question. They never write code or text. Every question has a time budget and a fixed fallback rule, and a receipt records which model answered.

Glossary

Go deeper

• Git compatibility: the push options and refs behind each verdict.
• Checks: what the pre-land check runs.
• Decision cards and reconcile: the ladder and the measurements.
• Architecture: the engine rules and the Cloudflare pieces.