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

| Label | Meaning | Owner (gross) | |---|---|---| | boucle:triage | Awaiting triage analysis | bot | | boucle:needs-info | Triage needs more info from the reporter | human | | boucle:spec-review | Spec validated by triage, awaiting human spec approval | human | | boucle:todo | Spec approved, queued for the worker | bot | | boucle:working | Worker is running | bot | | boucle:review | Worker shipped, awaiting reviewer verdict | bot | | boucle:approval | Reviewer PASSed, MR ready, awaiting human MR approval | human | | boucle:merging | Merger is running (rebase + merge) | bot | | boucle:done | Loop complete (merged + e2e PASS) | done | | boucle:human | Escalated to a human (iteration cap, unclear criteria, destructive change, etc.) | human | | boucle:blocked | Waiting on a dependency (sub-issue not closed) | bot | | boucle:split | Parent issue split into sub-issues, waiting for them | bot | | boucle:dnd | Transient flag: spec gate auto-validated during DND window | (rides along) | | boucle:autonomous | Transient flag: spec gate skipped per-issue opt-in | (rides along) | | boucle:recurring | Context tag: issue is part of a recurring bug class (non-blocking, survives transitions) | (rides along) | | boucle:board | The status-board issue (never dispatched) | — | | boucle:scheduled | Issue created by a schedule (cron template) | — |

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

| Label | Meaning | |---|---| | boucle::status::bot | The loop owns the next action (issue assigned to bot) | | boucle::status::human | A human owns the next action (issue assigned to human reporter) | | boucle::status::done | Terminal (loop complete) |

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

| Marker | Format | Written by | Parsed by | Purpose | |---|---|---|---|---| | <!-- boucle:agent --> | bare HTML comment | stamp_agent_marker (bin/forge/common.sh:81) on every forge_issue_note / forge_mr_note | has_agent_marker (bin/forge/common.sh:92) in dispatch.sh:99-103 | Distinguishes boucle's own writes from human replies. The primary anti-loop guard (invariant I7). A harness posting a comment MUST carry this stamp or dispatch treats it as a human reply and re-routes. |

3.2 Triage markers

| Marker | Format | Written by | Parsed by | Purpose | |---|---|---|---|---| | <!-- boucle:triage v=1 --> | v=1 (no attrs) | triage agent (final comment); draft promoted by triage.sh:178 (sed s/draft role=triage/triage v=1/) | triage.sh:163 (awk), collapse-duplicate-notes:71-72 (jq structural filter) | Marks a final triage comment. CI parser acts on it (sets disposition label, assigns, pauses). | | <!-- boucle:draft role=triage --> | role=triage | triage agent (first-pass draft) | collapse-duplicate-notes:73 (filter), triage.sh:178 (promotion source) | Marks a draft triage comment. CI parser does NOT act on drafts; log-scraping fallback promotes to final when the agent exhausts its steps. | | <!-- boucle:obligations v=1 --> | v=1 | triage.sh:213 | (informational — marks the obligations section of a triage comment) | Marks the obligations block in a triage comment (what the human must do next). | | <!-- boucle:needs-info v=1 reason=no-key --> | v=1 reason=no-key | triage.sh:92 (no-LLM-key gate) | triage.sh:55 (jq filter, idempotency check) | Marks a needs-info comment posted when the LLM API key is missing. Used for idempotency: triage checks if a no-key needs-info was already posted before re-posting. |

3.3 Verdict markers (reviewer / e2e)

| Marker | Format | Written by | Parsed by | Purpose | |---|---|---|---|---| | <!-- boucle:verdict v=1 role=reviewer sha=<hex> --> | v=1 role=reviewer sha=<short-sha> | reviewer agent (final verdict); draft promoted by reviewer.sh:381 | reviewer.sh:357 (SHA-anchored), :362 (SHA-unanchored fallback) | Marks a final reviewer verdict. SHA MUST be bare hex (no quotes/whitespace/angle brackets) — invariant I6. | | <!-- boucle:verdict v=1 role=e2e sha=<hex> --> | v=1 role=e2e sha=<short-sha> | e2e agent (final verdict); draft promoted by e2e.sh:192 |