Imported from ankaboot-source/supabase-selfhost-ops (SKILL.md). Install upstream with npx skills add ankaboot-source/supabase-selfhost-ops. Copyright stays with the author.

SKILL.md — Boucle protocol

Source of truth for the boucle protocol. This file is the behavioral contract: the labels, markers, state machine, and handoff rules that boucle speaks. It is runtime-agnostic (does not reference jcode internals) and forge-agnostic (covers GitLab + GitHub). A local harness (opencode, jcode, pi, or any agent runtime that reads markdown) loads this skill to "speak boucle" — interact with a boucle loop on any consumer repo correctly.

Projection at install: bin/setup symlinks .jcode/skills/boucle/SKILL.md → ../../SKILL.md so the consumer's harness loads it from the conventional skills directory. The source is this file; the symlink is the projection.

Enforcement: bin/check-doc-sync validates that the labels and markers in the engine code match this file. A label or marker in code that is absent here fails CI red — this file is the spec, not a description.

Relationship to other charters:

• AGENTS.md — contribution conventions + mandatory principles. LESSONS.yml — lessons (incident catalog). Lessons that state a current protocol invariant cross-reference this file (See SKILL.md §<id>); the normative text lives here.
• ARCHITECTURE.md — engine implementation (code structure, forge adapters, CI stages). The how, not the what.
• CONTEXT.md — identity, audience, philosophy, constraints. The why.
• README.md — overview, getting started. The entry.

1. Invariants

The protocol rests on ten invariants. Every agent (CI or local harness) and every human interacting with boucle MUST honor them. The LESSONS.yml lessons are incident catalogs that instantiate these invariants; the normative statement lives here.

I1 — Forge-native

Boucle lives in the forge. NEVER introduce a new frontend, a server, or a computer to keep running. The forge is the UI; labels are the state; comments are the channel. (CONTEXT.md §7, LESSONS.yml lesson #55.)

I2 — Label-driven state machine

Labels are the source of truth. No external database, no separate state API. The state machine is driven by boucle:* labels (detail axis) + boucle::status::* labels (gross axis: bot/human/done). A label change IS the state transition. (CONTEXT.md §7.)

I3 — Async by design

The human is not in front of the screen. Work happens asynchronously, driven by labels and comments. The loop does not wait for a human reply — it progresses to the next gate and parks at a human-readable state (boucle:spec-review, boucle:approval, boucle:human). (CONTEXT.md §1.)

I4 — Post-early

Post the comment or verdict FIRST, then refine. An incomplete draft posted is ALWAYS better than a refinement never posted. Step-budget waste (the agent exhausts its budget without posting) is bug #1. (LESSONS.yml lesson #1, #2, #5.)

I5 — Idempotence

All bin/* scripts and label writes MUST be idempotent. Re-running a script produces no additional side effects. A label PUT that does not change the label set is skipped (the forge records a Resource Label Event on every PUT, even a no-op — CONTEXT.md §8). (LESSONS.yml lesson #4.)

I6 — SHA-anchored verdicts

Reviewer and e2e verdicts MUST include the commit SHA as bare hex: no quotes, no whitespace, no angle brackets. Exact format: <!-- boucle:verdict v=1 role=reviewer sha=abc123def456 -->. The CI parser FAILS if the format is not respected. (LESSONS.yml lesson #6, #41, #47.)

I7 — Marker-based self-recognition

Boucle recognizes its own writes by an invisible stamp (<!-- boucle:agent -->), NEVER by the actor's identity. A comment posted without the stamp is treated as a human reply and routed. This is mono-user-safe (when bot and human share an account, the marker discriminates; the actor does not). Every comment a harness posts MUST carry the stamp, or dispatch will treat it as a human reply and re-route. (LESSONS.yml lesson #55.)

I8 — Doc-as-code

A doc that describes a system that no longer exists is a bug. Charter docs are maintained as part of each work cycle: triage identifies impacted docs, worker updates them in the same MR, reviewer verifies conformance, e2e verifies production match. bin/check-doc-sync enforces code ↔ SKILL.md sync in CI. (AGENTS.md "Documentation self-maintenance".)

I9 — Upstream-first

Fix upstream (in boucle) FIRST, then update the consumer, then remediate existing data. NEVER patch a consumer to work around a boucle defect. NEVER introduce a local workaround that won't be reported upstream. (CONTEXT.md §7, .jcode/UPSTREAM-FIX-WORKFLOW.md.)

I10 — Serial merge

Merges are serialized via resource_group: boucle-merge. Each rebase is against a master/main that includes previously-merged MRs. NEVER parallelize merges — a concurrent rebase against a stale branch produces conflicts and race conditions. (CONTEXT.md §7, LESSONS.yml lesson #8.)

2. State machine

The state machine is two-axis: a detail label (boucle:<state>) that answers "what is the loop doing?" and a gross label (boucle::status::<owner>) that answers "whose side is this on?". In mono-user mode (BOUCLE_MONO_USER=true) the gross axis is dropped (one actor owns both sides — the question is meaningless).

2.1 Detail labels

Removed (dead labels, pruned from bin/setup): boucle:approved, boucle:spec-approved. MR approval uses the native forge Approve button; spec approval uses a canonical emoji reaction (👍 ❤️ 🎉 🚀) on boucle:spec-review — a text reply amends the spec and re-triggers triage, it does NOT approve. Neither uses a label.

2.2 Gross labels

2.3 State diagram

stateDiagram-v2
    [*] --> triage: issue opened / bot assigned
    triage --> needs_info: triage needs more info
    triage --> spec_review: triage validated spec (Size S)
    triage --> todo: triage validated spec (auto / DND / autonomous)
    triage --> human: Size L / unclear criteria / destructive
    triage --> split: issue too big, split into sub-issues
    needs_info --> triage: human replied (note on needs-info)
    spec_review --> todo: human approved spec (👍 ❤️ 🎉 🚀 emoji)
    spec_review --> triage: human replied with amendment (re-triage)
    spec_review --> human: human rejected / no response
    todo --> working: worker started
    working --> review: worker shipped code
    working --> todo: worker no-changes / build-fail (retry, iter < max)
    working --> human: worker iteration cap / API down (exit 4)
    review --> approval: reviewer PASS
    review --> todo: reviewer FAIL (retry, iter < max)
    review --> human: reviewer FAIL (iter cap) / UNCERTAIN / no verdict
    approval --> merging: human approved MR (native Approve button)
    approval --> review: MR updated (push to boucle/<iid>)
    approval --> human: MR closed without merge
    merging --> done: merge succeeded + e2e PASS
    merging --> human: merge conflict / not mergeable
    done --> [*]
    human --> triage: human re-assigns bot (BOT_JUST_ASSIGNED)
    human --> [*]: human closes issue
    split --> triage: all sub-issues closed (parent re-queued)
    blocked --> todo: dependency closed (unblock)

2.4 Transition table

The transition table is derived from the handoff primitives in §4. Every transition is effected by set_boucle_label <iid> <detail> <gross> (lib/boucle.sh:626), which preserves non-boucle labels, writes the detail+gross pair idempotently, reassigns the issue (bot on boucle::status::bot, human reporter on boucle::status::human), and fires the outbound notification on the transition (never on the state).

3. Marker reference

Boucle communicates via invisible HTML-comment markers stamped on issue/MR comments and via structural sections in comment bodies. The markers are machine-readable; the structural sections are detected by pattern. A local harness MUST use the markers correctly or dispatch will misroute its writes.

3.1 Self-recognition marker

3.2 Triage markers

3.3 Verdict markers (reviewer / e2e)

3.4 Dependency / hierarchy markers

3.5 Operational markers

3.6 Markers NOT in code (do not emit)

3.7 Structural signals (not HTML comments)

4. Handoff protocol

The handoff protocol defines how a human (via the forge UI or a local harness) interacts with the loop. Every handoff is a webhook event routed by dispatch. The primitives below are extracted from lib/boucle-ci/dispatch.sh — they are the real mechanisms, not invented verbs.

4.1 Re-queue after boucle:human — bot reassignment

boucle:human is a dead-end for comments. A plain note on an issue at boucle:human matches no dispatch branch and falls through to exit 0 — nothing happens. The ONLY re-queue path is re-assigning the issue to the bot.

When a human assigns the bot to an issue (any idle state: boucle:human, boucle:needs-info without reply, unlabeled, boucle:todo, boucle:spec-review), the issue update webhook fires with an assignee change. Dispatch detects BOT_JUST_ASSIGNED (dispatch.sh:504-539) and routes to triage from any idle state. This is the explicit "reopen and resume" signal.

A local harness that wants to re-queue a boucle:human issue MUST re-assign the bot, not post a comment. (LESSONS.yml lesson #11, #44.)

4.2 Spec approval — emoji only; a reply amends

To approve a spec (issue at boucle:spec-review), the human awards a thumbsup heart rocket or tada emoji on the triage/spec-review note (dispatch.sh, gated by BOUCLE_SPEC_APPROVAL_EMOJIS="thumbsup heart rocket tada"). The emoji triggers chain_to_role worker. An emoji by the bot account is skipped — only human emoji count.

A text reply is NOT an approval — it is a correction/amendment. A reply re-triggers triage (chain_to_role triage), which re-reads the human's notes and posts an updated spec back at boucle:spec-review for another approval round. The triage validation message says so explicitly: “A reply never approves the spec.” A bot-authored note (carrying <!-- boucle:agent -->) is skipped before routing.

The doctor's orphaned-boucle:spec-review recovery mirrors this contract: an emoji re-triggers the worker; a reply re-triggers triage.

The same emoji set re-triggers triage from boucle:needs-info (e.g. after the user adds an API key following a no-key or quota-exhausted help message).

4.3 MR approval — native forge button

To approve an MR (issue at boucle:approval), the human clicks the forge-native Approve button on the MR. This fires the merge_request approved webhook (dispatch.sh:167-185) → chain_to_role merger. A 👍 emoji on the MR does NOT trigger the merger (emoji approval is spec-only).

Native-approval race (reviewer.sh:487-497): if the human approves the MR before the reviewer finishes (issue still at boucle:review), the approved webhook is silently dropped (dispatch requires boucle:approval/human). The reviewer's PASS branch checks forge_mr_approvals and triggers the merger directly to recover.

4.4 Push to boucle/<iid> — re-review

A push to the worker branch (boucle/<iid>) fires merge_request update (dispatch.sh:187-205). If the issue was at boucle:approval, it reverts to boucle:review and re-runs the reviewer (the approval is invalidated by the push). Otherwise it re-runs the reviewer on the updated MR.

4.5 MR close — label-dependent

Closing the MR (not merging) fires merge_request close (dispatch.sh:207-258):

• boucle:done / boucle:human → no-op (terminal).
• boucle:approval → escalate to boucle:human (user decision).
• any other (boucle:todo/working/review/merging) → revert to boucle:todo + chain_to_role worker (fresh start).

4.5b MR events on GitHub — vocabulary translation

§4.3–4.5 describe the MR webhooks in the GitLab vocabulary, which is what the router's case arms match: open, update, close, reopen, approved, unapproved, merge. GitHub sends different words, and its payload puts the MR under .pull_request rather than .object_attributes. Both are normalized in dispatch before routing — dispatch_github_mr_action for the verb, a two-shape jq filter for the branch and IID:

A merge arrives as a close on GitHub; only .pull_request.merged tells the two apart, and that bit decides catchup versus a worker re-run. synchronize must also be in the workflow's pull_request trigger types — without it GitHub never delivers the event, and a PR is checked once at open and never again on later pushes.

4.6 Comment on MR — worker re-run with feedback

A human comment on the MR (dispatch.sh:331-359) reverts the issue to boucle:todo and re-runs the worker with BOUCLE_ITERATION=verdicts+1 and the MR notes injected as BOUCLE_REVIEWER_FEEDBACK. This is the feedback channel that feeds human amendments forward (LESSONS.yml lesson #16, #53).

On GitHub the equivalent event is an issue_comment on a pull request: the payload carries .issue.number (the PR number) with .issue.pull_request non-null. dispatch must detect this via dispatch_is_github_pr_comment (dispatch.sh:38-49) and route it to the same MR-note handler, resolving the PR's source branch via forge_mr_get (it is not in the payload). Without this, the PR's (empty) labels would trip the dispatch ABORT gate and human PR feedback could never re-trigger the worker.

4.7 Closed-issue guard

Any webhook (note/emoji/update) on a closed issue is a no-op (dispatch.sh:385-411) — EXCEPT bot assignment, which is the explicit "reopen and resume" signal (dispatch.sh:404-412). A local harness MUST NOT re-trigger a closed issue by any other means. (LESSONS.yml lesson #44.)

4.8 Anti-loop filters (apply to ALL events)

The 👀 filter is not redundant with the bot-identity filter: in mono-user mode there is no bot account, so ACTOR is the human on every event — including boucle's own reaction. Where emoji events reach dispatch at all (bin/setup writes emoji_events=false, but a pre-existing hook may have it on), triage's own acknowledgement would otherwise land on an issue still labelled boucle:triage — a label that routes to triage unconditionally — and the loop would re-triage itself.

A local harness posting a comment MUST let the stamp be applied (via forge_issue_note / forge_mr_note or by including <!-- boucle:agent --> manually) or its comment will be treated as a human reply and re-route the loop. (I7.)

4.9 Cross-role chaining

Every role transition funnels through chain_to_role <iid> <role> [var=value] (lib/boucle.sh:1030) → forge_trigger_role (bin/forge/gitlab.sh:503 / github.sh:514), which fires a pipeline trigger with BOUCLE_ISSUE + BOUCLE_ROLE + extra vars. A local harness does NOT call chain_to_role directly — it sets the label and lets dispatch route on the next webhook, OR it re-assigns the bot (§4.1) to re-trigger triage.

5. Forge abstraction contract

The engine speaks to the forge through a thin seam (bin/forge/<forge>.sh + bin/forge/common.sh). A local harness interacting with boucle SHOULD use the same primitives (or their forge-native equivalents) so its writes are indistinguishable from the engine's.

Marker stamping is mandatory. Every comment posted via forge_issue_note or forge_mr_note carries <!-- boucle:agent -->. A harness that posts via the raw forge API MUST add the marker manually, or dispatch will treat the comment as a human reply (I7).

6. Branch contract

The worker branch is boucle/<iid> (e.g. boucle/42). The lifecycle:

• Worker creates the branch from master/main, implements, pushes, opens an MR targeting master/main.
• Reviewer reviews the MR diff / deployed preview.
• Merger rebases the MR onto master/main (serially, via resource_group: boucle-merge) and merges.
• Catchup closes the issue after merge.

A local harness taking over an issue at boucle:human SHOULD work on the existing boucle/<iid> branch (not a new branch) to preserve the worker's commits. If the branch is stale, rebase onto master/main before pushing. If the branch is absent, create boucle/<iid> from master/main.

Never push to master/main directly — the merger owns that transition. A harness that pushes to master/main bypasses the serial-merge guard (I10) and may produce conflicts with in-flight MRs.

7. Known gaps

• Dogfood suspended. The engine repo no longer dogfoods on a consumer (urgence-palestine.fr split out). Dogfooding will resume via a dedicated test consumer once the engine/consumer separation is stable. Until then, the 73 LESSONS.yml lessons catalog the forward-looking operating principles; new classes of bugs are discovered on real consumers. (CONTEXT.md §1.)
• Lesson numbering drift. AGENTS.md has duplicate lesson numbers (#17, #22, #23, #24, #27, #28, #29, #41, #42, #47 appear twice). The doc's own rule says "never renumber — a pruned entry leaves a gap, not a shift", but collisions are not gaps. A curation pass will resolve this; until then, reference lessons by their unique first sentence, not by number alone.

8. Interactive mode

A local harness (opencode, jcode, or any agent CLI that reads markdown) can take over a boucle issue, work on it interactively, and hand it back to the loop. This section documents the commands, the protocol, and the conventions the harness MUST respect.

Commands

The bin/boucle wrapper exposes six verbs. All require forge auth env vars (see §Forge auth below).

Posting comments

Always use bin/forge-note (not raw glab/gh note commands) so the <!-- boucle:agent --> marker is applied. Without the marker, dispatch treats the comment as a human reply and re-routes the loop (I7).

bin/forge-note issue <iid> --message "comment body"
bin/forge-note issue <iid> --message-file /path/to/message.md
bin/forge-note issue <iid> --message-stdin < file
bin/forge-note mr <mr_iid> --message "comment body"

Read-only inspection

bin/health <iid>        # per-issue health summary (iterations, outcomes, cost, verdict)
bin/doctor --audit      # read-only board audit (~20 checks)

Excluded commands (CI-context only)

These bin/* commands require CI env vars and are NOT available locally. Use the local alternatives:

Forge auth in local mode

Set these env vars before running bin/boucle or bin/forge-note:

export BOUCLE_BOT_TOKEN="glpat-..."   # or GH_TOKEN for GitHub
export BOUCLE_FORGE_HOST="gitlab.com" # or github.com
export BOUCLE_PROJECT_PATH="org/repo" # project path
export BOUCLE_FORGE="gitlab"          # or "github"

The agent CLI can also use glab/gh directly for forge operations (list MRs, view issues, etc.) — bin/forge-note is just a wrapper that applies the <!-- boucle:agent --> stamp.

Message templates

The templates/ directory at the repo root contains one .md file per boucle message type, with {{placeholders}}. These are the single source of truth for the format. To produce a boucle-valid message:

1. Read the template (e.g. templates/triage.md).
2. Fill the placeholders with the actual content.
3. Post via bin/forge-note issue <iid> --message-file <path>.

Protocol

# 1. Check the issue state
boucle status <iid>

# 2. Take over
boucle pause <iid>
boucle check <iid>

# 3. Work in the agent CLI on boucle/<iid>
#    (read state.md, fill templates/, commit, push)

# 4. If new spec/conception was done:
#    fill templates/triage.md, post via bin/forge-note

# 5. Hand back to the loop
boucle resume <iid>   # if code pushed → review+merge
boucle restart <iid>  # if starting from scratch

Critical rules

1. Work on boucle/<iid>, never push to master/main — the merger owns that transition (I10).
2. Always use bin/forge-note for comments — the <!-- boucle:agent --> stamp prevents dispatch from treating your comment as a human reply (I7).
3. Run boucle check before coding to avoid file-gate conflicts with in-flight issues.
4. Use templates/ for any boucle-format message (triage, verdict, state.md) — do not improvise the format.
5. Read state.md and iterations.md before starting work — they contain the goal, acceptance criteria, and what previous iterations tried.
6. Update state.md (Approach section) and append to iterations.md after working — the loop's reviewer reads them.
7. All code, templates, and CLI output are in English — this matches the boucle convention (charter docs, agent prompts, CI scripts are all in English).

9. Failure mode framework

The invariants (§1) are the rules; this section names the patterns those rules prevent. The LESSONS.yml lessons are incident catalogs that instantiate these patterns — the framework gives them a shared vocabulary so a new failure can be classified against a known class, not rediscovered from scratch.

The patterns below are adapted from the Multi-Agent Systems Architect body of knowledge (distilled pipeline-design patterns that independently converge on boucle's hard-won lessons). The mapping is boucle-specific: each pattern names the detection signal, the recovery path, and the lessons that instantiate it.

9.1 Failure taxonomy

Every agent run in the loop can fail in one of seven modes. Each mode has a detection signal and a recovery path already encoded in the engine.

A new incident that does not fit one of these seven modes is a new class of failure — the worker MUST add a lesson AND a taxonomy entry. A new incident that does fit a known mode is an instance, not a new class — the worker adds a lesson cross-referencing the mode, not a new taxonomy entry.

9.2 Circuit breaker

The fallback-provider logic (lesson #30) is a circuit breaker. The states:

The exit-4 path (bin/jc exits 4 on empty log / no activity) is the trip mechanism. The diagnostic comment posted on the issue names the model and tells the human to check API status — this is the "always produce something" rule (§I4) applied to the failure path itself.

9.3 Fallback chain

Every role in the loop has a fallback chain. The system MUST always produce something — a structured degraded response beats a silent failure (§I4).

9.4 HITL gate calibration

boucle:human is the HITL gate. The calibration problem applies directly:

• Over-escalation → the human rubber-stamps → the gate is theater. Caused by: iteration cap too low, reviewer too strict, doctor too aggressive.
• Under-escalation → the human never sees edge cases → false confidence. Caused by: reviewer PASSing unaddressed amendments (lesson #53), doctor not scanning boucle:merging (lesson #68).

Gate placement in boucle is label-driven, not code-driven:

9.5 Observability contract

The engine's observability is agent-output.log + the marker/verdict system. The minimum per-run record:

The root-cause analysis protocol maps to the doctor's audit: identify blast radius (which issue/MR), trace backward (which role produced the bad output), isolate the failure (agent vs upstream vs inter-role contract), classify (prompt ambiguity / context overload / model limitation / schema mismatch / missing info), fix + regression test.

9.6 Context budget

The loop's context management is state.md + iterations.md persisted to $BOUCLE_STATE_CACHE (lesson #28). This is the "structured state object" pattern: each role reads only its required fields (goal, approach, tried, awaiting) and writes only its output fields. The checkpoint is the iterations.md append — a compressed record of what was tried, so the next iteration does not re-discover it.

See also

• AGENTS.md — contribution conventions + lessons learned (incident catalog)
• ARCHITECTURE.md — engine implementation (code structure, forge adapters, CI stages)
• CONTEXT.md — identity, audience, philosophy, constraints
• README.md — overview, getting started
• .jcode/UPSTREAM-FIX-WORKFLOW.md — upstream fix workflow