Beagle SCM

The parallel agent ticket-driven fix-and-land work loop

Issues are cleared by a fleet of background agents — one per ticket, each in its own isolated clone. In fact, agents are incredibly dumb and mess things up all the time. Most of the time, they break way more than they fix. For that reason, we use these procedures to discard their bullshit output most of the time, hoping the rest is OK.

1. Issues can be reported by the user OR created by an agent that hit them. The latter requires explicit user request. A tickettodo is created from that with maximum context and evidence.
2. An agent is forked to work on the issue. The agent uses its own worktree, not touching the main tree. On any suspicion of feeding bullshit, the worktree is rm -rf-ed by the user, with no side-effect.
3. An agent must start with making a minimalistic repro for the issue, as a test. No-repro work can only be permitted explicitly by the user. Overall, all claims must be verified.
4. Then, an agent fixes the code to overcome the issue. No other tests can be edited, unless permitted explicitly by the user.
5. Once the work is done and all tests pass, the agent reports to the user. If some tests contradict the new behavior and better be amended, request the user.
6. The user may inspect the changes and merge them back or order the agent to merge, explicitly, or request adjustments.
7. Any suspected bullshit is rm -rf-ed immediately, chat cleared, restarted again in smaller pieces with a better spec or simply done the normal way with no LLMs.
8. Agent's work better be pre-approved by the orchestrating agent, so obvious bullshit is bounced. The orchestrator tries to verify whether anything was actually fixed (inspects and runs the test/scenario in question), also the style.
9. The point of this process is to prove the generated code is not complete BS and mutates the codebase in a roughly correct direction, while not touching any unrelated parts.
10. Discarding 90% of LLM output is not a problem at all. Hitting new random bugs in random parts of a codebase in every next build is the real problem. Adding more bugs than fixing is a problem. A sprawling unreadable codebase is a problem.
11. An agent should not try to show off its "reasoning" by dumping screenloads of BS on the user. No one wants to read that anymore. Half a page is the reasonable amount of output unless user requested more. May use formatting (bold, lists, colors) for better readability.
12. On the first violation of these norms, code is rm -rf-ed, chat is cleared, other ways are sought. If something was written, it was written to be read.

Typical CLI commands

1. Worktree life cycle (in a VM, SRC_ROOT=$HOME normally)
   • be=jab the JavaScript impl (reads js files from be, not node_modules)
   • mkdir $SRC_ROOT/<TICKET>, then either
   • cd $SRC_ROOT/<TICKET>
     • a store-backed worktree: $be get file:/$SRC_ROOT/.be?/project

- a full clone: $be get be://localhost?/project

1. Building
   • cmake is used for everything
   • ninja, not make
   • ctest -j16 for testing or ninja -j16 test
2. Reviewing the changes
   • $be or $be status see the state of the tree,
   • $be diff or $be diff path see the changes, including branch ahead/behind,
   • $be get update from the tracked branch, $be get \? from the trunk.
3. Relevant projects
   • libabc,
   • beagle the C version, including libdogenizer,
   • beagle-ext the JS version and extension scripts,
   • beagle-ext-tests the JS version tests.
4. When these commands fail, agents must not improvise, but report.
5. Merged, nixed or wontfixed worktrees can be rm -rf-ed.

Norms of politeness.

• Commit message is 1 line max (64 chars), must start with the ticket code. More bullshit is not helpful.
• Code comments are 2 lines max, better start with the ticket code. Moronic 10-line comments better be avoided.
• When editing the code, read relevant past tickets for the context. Stable code vandalization seems to be an issue.
• Any Beagle bugs during the session should be proposed as tickets (with maximum context added, see todo)

Things NOT TO DO

I repeat: don't do this!

1. copying worktrees around with cp -r
2. parsing URIs with regexes (or manually in C!) or manually composing them
3. do not touch the main tree; certainly do not do any rev control there;

   may only do small edits with explicit permission; work in worktrees