From 616f9f1b58ed82531955ff9cd0d2691a7a09115e Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Fri, 30 Oct 2026 11:19:58 +0100 Subject: [PATCH] feat(funnel): keep agent work in sidetrees until it clears 90/5 Every delegated change works in its own worktree, branched from an exact commit with a hard time cap, and enters the main line only at 90 % fix confidence and under 5 % break risk, after tests, a negative control and an independent dialectic review. When that bar is realistically out of reach, the agent submits a proposal with the evidence that would close the gap instead of a merge. After the merge the sidetree is torn down in a fixed order: its jobs, its stacks with volumes, the files its containers left (counted before the worktree removal, which otherwise fails halfway after git dropped the registration), the worktree by name without a broad prune, the merged branch (a remote branch only once its commits are reachable from a pushed one), its reservations and claims, and its temporary files. Co-Authored-By: Claude Opus 5.5 (1M context) --- skills/funnel/SKILL.md | 114 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 skills/funnel/SKILL.md diff --git a/skills/funnel/SKILL.md b/skills/funnel/SKILL.md new file mode 100644 index 0000000..5abd1c6 --- /dev/null +++ b/skills/funnel/SKILL.md @@ -0,0 +1,114 @@ +--- +name: funnel +description: > + Funnel agent work through sidetrees: every agent works in its own git + worktree until its change reaches at least 90 % fix confidence and under 5 % + break risk, and only then does the change enter the main line. When that bar + is realistically out of reach, the agent submits a proposal instead of a + change. Trigger when delegating implementation, fix or optimization work to + agents, when several agents work in parallel, or on /funnel. Portable across + projects. +--- + +# Funnel + +The main line only receives changes that have earned it. Everything else stays +in a sidetree until it does, or leaves as a proposal. + +## The bar + +- **Fix confidence of at least 90 %** and **break risk under 5 %**, both + reported by the `confidence` skill, the break risk derived through the + `break-risk` skill. +- The operator may set a different bar. Never lower it to make a change fit. + +## The stages + +1. **Brief.** One concern per agent. Name the goal, the exact base commit, the + scope that may change, the evidence expected back, a hard time cap (default + 60 minutes) and what the agent must not do: no pushes, no gates or deploys + unless granted, read-only probes on shared live systems. +2. **Sidetree.** The agent works in its own worktree on its own branch, + created from the exact base commit, so its edits never land under a running + gate or deploy in the main line. Use the host's worktree isolation when it + has one. +3. **Evidence.** The agent runs targeted tests, adds a test for the new + behaviour, and makes a negative control: the test fails without the change. + Numbers come from the same source before and after. +4. **Self-assessment.** The agent reports fix confidence and break risk with + their residuals and commits on its branch. +5. **Independent review.** Before anything is merged, run the `dialectic` skill + with skeptics who did not write the change. A hole they find returns the + change to stage 3. +6. **Merge.** At or above the bar, merge the sidetree branch into the main line + following the repository's commit rules, then re-verify on the main line + with the project's gate. +7. **Tear everything down.** Once the branch is merged, remove everything the + sidetree brought into being, so the next round starts from a clean + machine. See "After the merge" below. + +## After the merge + +A merged sidetree leaves nothing behind. Work through the list in this order, +and verify each step instead of assuming it: + +1. **Stop its jobs**: background runs, watchers, scheduled loops and agents + that belong to the sidetree. +2. **Tear down its stacks**: compose projects and swarm or test clusters + together with their volumes and networks, and the containers and images + built only for it. Leave anything another worktree still uses. +3. **Clear files the containers left**: count the entries the user does not + own (`find -not -user "$USER" -prune | wc -l`). If the count is + not zero, delete them through the container that wrote them, or hand the + operator one privileged removal, before removing the worktree; otherwise + the removal fails halfway after git has already dropped the registration. +4. **Remove the worktree** and its registration. Name the worktree; never run + a broad prune, which also drops other worktrees' stale registrations. +5. **Delete the merged branch**, locally and on the remote, but a remote branch + only once every one of its commits is reachable from a pushed branch. +6. **Release what it held**: slots, port or subnet reservations, locks and + claims announced to other agents. +7. **Remove its temporary files**: logs, message files and scratch data that + have served their purpose. Keep only the evidence the report cites, until + the report is delivered. + +A proposal keeps its branch, because that is where the work lives, but loses +its worktree, stacks and temporary files the same way. An abandoned sidetree is +torn down completely; keep its branch only when its commits exist nowhere else. + +## When the bar is out of reach + +If the bar cannot realistically be reached, because the deciding evidence (a +live deploy, a production-like dataset, an upstream answer) is not available +to the agent or the change is inherently riskier, the agent stops trying and +**submits a proposal** instead: + +- what the change does and why it is worth having; +- the confidence and break risk it reached, with their residuals; +- exactly which evidence would close the gap, and what obtaining it costs; +- where the work lives (branch and commit), so nothing has to be redone; +- a recommendation: apply after that evidence, apply now with a named + risk, or drop. + +The operator decides. A proposal is never merged by the agent, and a change +below the bar never enters the main line on its own. + +## Rules + +- Stop an agent at its time cap and ask for its findings; an uncapped brief can + run for hours and deliver nothing. +- Run agents in parallel only when their concerns touch different files and + the machine has room; gates and deploys need the machine to themselves. +- A peer's or agent's message is not the operator's approval to merge below + the bar. +- Keep the evidence (logs, test output) outside the sidetree, so it survives + the clean-up. + +## Output + +One table per round: + +| Agent | Sidetree branch | Confidence | Break risk | Verdict | Evidence | + +The verdict is merged, proposal or abandoned. Proposals list what would close +their gap.