Tree places new Bots up front: reuse before create, project teams as lead plus children, create under own descendants

[Birfy]

Fixes #447

Summary

Forward allocation for the Bot tree, built on #446's self-organization (#448 / #453). New Bots go in a sensible place up front. The auto-prune/merge path stays the safety net.

1. Reuse before create. New read-only tool find_bots(query?), visible to every tree Bot. It lists the Bots in the caller's branch (for Chief, the whole tree) with name, role, parent, depth, path, children, lead and via (the caller's child on the path). With a query, it returns matches only, best first. create_child_bot checks the whole branch first. If a Bot with the same role exists at any depth, it returns { reused, note } and creates nothing. Tested with the match at depth 3.

2. Lead plus children. New tool create_team(team, members, parent?). It creates "<team> Lead" with the members under it, so Chief → FlyBot Lead → {Dev, Test, Maintenance, Repo} takes one slot under Chief. It uses roles.js keys and labels, canLead, and organize's createLead / markLead. If a lead for that group already exists, it is reused. Members that already exist with the same role are reused too. A reused member that sits flat next to the lead moves under it, which frees its slot. There is never a least-loaded fallback. With no parent, create_child_bot puts a later Bot of the group under that group's marked lead ("FlyBot Docs" → under FlyBot Lead).

3. create_child_bot(name, role_description, parent?). parent can be an id or a unique name. It must be the caller or one of its descendants; anything else gets "parent must be you or one of your descendants". Limits, depth and the sibling-name check run at the target, under that parent's existing lock. Tested: refusal of a sibling, an ancestor, an outsider and an unknown parent, plus limits checked at the target.

4. Shared primitives. organize.js now exposes organizer.shared (profile, subtree, homes, fits, createLead, markLead, move, journal, the reorganization queue). The new src/allocate.js uses only these, so there is no second implementation. A team that moves or marks existing Bots is a journaled run (trigger team), and the tree view's existing Undo reverses it.

5. Prompts and docs. Coordinator / Chief prompts now state the placement rules:

   • call find_bots first and reuse what fits
   • a project with several roles gets a lead plus children (create_team)
   • at maxChildren - 2 children or more, group related children instead of adding another flat one
   • name the tree path of every new Bot
   • a full level, orphans and duplicates are fixed by the automatic reorganization, without asking the owner first

   Orphans (a member whose parent is no longer in the tree) are now reattached on each repair pass: by role to their group's lead, else the root, with their subtree, as a journaled move. One that fits nowhere yet is retried on the next pass. docs/subsystems/tree.md has a new "Placement rules" section linked to Tree: close create_bot maxChildren bypass; auto-prune/merge when over capacity or orphans exist #446. README and changelog fragment updated.

6. Plan card: deferred. The codebase has no chat card for a model-proposed plan with Approve / Edit / Cancel. The only approval cards are social's message holds, and the tree only has the sidebar reorg notice. Building one would mean a new chat slot, host endpoints and resuming the model's turn, which is not small. Forward allocation goes ahead and its result names the tree paths. The deferral is recorded on Tree: smarter sub-Bot allocation (lead+children, reuse, deeper placement) maintained by auto-prune/merge #447. Automatic reorganization never asks first.

Minor decisions (made by me)

• Duplicate check scope is the caller's own branch (Chief: the whole tree). A Bot only manages its own downstream. Duplicates across branches are merged by the daily tidy.
• Reuse match is Tree organizes itself by role: groups under leads, merge, daily tidy, undo #448's sameRole: same name once generic words are dropped and no conflicting description, or near-identical descriptions. A same-name Bot with a different description is created, not reused. find_bots matching is fuzzier: query in name or role, shared role-word stems ("test" finds "Tester"), project, domain.
• Automatic deeper placement (no parent) only goes under a Bot already marked as a group lead (lead field), only down a path of groups the new Bot belongs to, never under a namesake, and never under a lead of a group the new Bot could lead itself. Unmarked lead-like Bots are left to Tree: close create_bot maxChildren bypass; auto-prune/merge when over capacity or orphans exist #446 grouping. Otherwise the parent is the caller, as before.
• create_team members are "Name: role" strings. The host keeps only type/description/enum/items, and DSH refuses object items without declared keys. { name, role_description } objects are also accepted. A team has 2 to maxChildren members. Team name is at most 35 characters, so that " Lead" fits the 40-character name limit.
• Team lead lookup: an existing lead of the group is searched in the caller's whole branch (marked for it, named "" or " Lead", or coordinating it). If one exists, it is reused even when parent names another place, so no second lead is made.
• Full target: create_child_bot and create_team keep the limit reached refusal (the Tree: close create_bot maxChildren bypass; auto-prune/merge when over capacity or orphans exist #446 contract). The message points to parent or the automatic regroup. A team still fits at a full level when it reuses a flat member, because the lead takes that member's slot.
• Journal: a fresh team (only new Bots) is a plain create, with no journal entry and no "Tree reorganized" notice. Only runs that move or mark existing Bots are journaled. In Chief's prompt they are named "Last tree reorganization", without "automatic".
• Orphan definition: parent set to an id that is not a tree member. Bots with parent: null keep today's handling.

Tests

• plugins/tree/test/tree.test.js: 6 new #447 tests:
  • reuse at depth 3 and find_bots (scope, fields, ranking, branch-only)
  • parent refusal and limits at the target, including the lock under parallel creates
  • team as lead plus children, one slot, lead and member reuse, later Bots joining the lead, prompt rules, bad input
  • team at a full level reusing a flat member, journal and undo
  • orphan reattachment
  • without parent, a new Bot goes only down leads of groups it belongs to
• fix 4 adjusted, because parent is now a known argument.
• plugins/tree/test/host.test.js: new real-host test. The schemas compile under DSH, and find_bots, create_team and create_child_bot(parent) work end to end.
• ARCH_DOCS_BASE=origin/main TZ=UTC npm run verify passes. node scripts/lint-plugins.mjs tree|social|timeline, node .github/scripts/check-pack.mjs and node .github/scripts/changelog.mjs check also pass. Plugin tests ran with DSH_HARNESS and none were skipped.
• Not run: live Mac E2E (nothing deployed or restarted).

Risk tier: T3

[Birfy]

Self-review: PASS
Tip SHA: 45fb3e8
Ran: ARCH_DOCS_BASE=origin/main TZ=UTC npm run verify (with DSH_HARNESS, 0 skipped); node scripts/lint-plugins.mjs tree|social|timeline; node .github/scripts/check-pack.mjs; node .github/scripts/changelog.mjs check; PR CI all green (Test, plugins tree/social/timeline, package, tests-ok)
Not run: live Mac E2E (nothing deployed or restarted)
Checked the diff against #447's acceptance criteria and the owner decisions:

• Reuse before create: find_bots covers the caller's own branch only. create_child_bot reuses a same-role Bot at depth 3, tested.
• Lead plus children: create_team builds Chief → FlyBot Lead → {Dev, Test, Maintenance, Repo} in one slot, using Tree organizes itself by role: groups under leads, merge, daily tidy, undo #448's roles.js and createLead / markLead / move / journal. There is no least-loaded fallback.
• create_child_bot(parent?) refuses a sibling, an ancestor, an outsider and an unknown parent. Limits are checked at the target, under its per-parent lock.
• Orphans are reattached by role (journaled, undoable). Prompts and docs/subsystems/tree.md state the placement rules and leave overcapacity, orphans and duplicates to Tree: close create_bot maxChildren bypass; auto-prune/merge when over capacity or orphans exist #446. The plan card is deferred, as commented on Tree: smarter sub-Bot allocation (lead+children, reuse, deeper placement) maintained by auto-prune/merge #447. Nothing is deleted, published or auto-granted.