AGENT SKILL

boucle

The boucle protocol — the labels, markers, state machine and handoff rules a boucle loop speaks. Use when interacting with a boucle loop on any consumer repository: reading or writing boucle:* labels, emitting or parsing <!-- boucle:* --> markers, posting a SHA-anchored verdict, driving an issue through triage/worker/reviewer/e2e, or answering "what is this loop waiting on". Runtime-agnostic and forge-agnostic (GitLab and GitHub).

License 许可
AGPL-3.0
最近更新
2026-11-14
Stars
★ 2
Forks
0

01 前言 Front Matter

name
boucle
description
The boucle protocol — the labels, markers, state machine and handoff rules a boucle loop speaks. Use when interacting with a boucle loop on any consumer repository: reading or writing boucle:* labels, emitting or parsing <!-- boucle:* --> markers, posting a SHA-anchored verdict, driving an issue through triage/worker/reviewer/e2e, or answering "what is this loop waiting on". Runtime-agnostic and forge-agnostic (GitLab and GitHub).

02 资源文件 164

03 SKILL.md 正文

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.)

"Post early" means minimal but meaningful, not an empty placeholder. A draft MUST contain at least the content the human needs to act on it — for triage, a rough ## Analysis section (2-3 sentences restating the issue) and a ## Metadata section carrying a Disposition. An empty placeholder ("DRAFT — first-pass triage, refining next.") is noise the human cannot act on: no analysis, no questions, no criteria. The agent MUST read the issue body (already in its prompt as $BOUCLE_ISSUE_BODY) before posting — "post early" does NOT mean "post before reading the issue". (LESSONS.yml lesson #99.)

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.)

The same marker discriminates note authorship in prompts: CI MUST tag every note injected into an agent prompt [<author> — boucle] when its body carries the stamp, [<author> — human] otherwise, and agents MUST classify authorship by that tag — NEVER by the posting account (in mono-user mode the account is shared, so identity discriminates nothing; a human amendment posted under the bot's account is still a binding amendment, lesson #111). (LESSONS.yml lesson #111.)

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:approved Human approved the spec (GitHub: label added by author) bot
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) —
boucle:retro The retro's local per-run report issue (never dispatched) —
boucle:report Upstream retro proposal — anonymized case or plan, created on BOUCLE_UPSTREAM_REPO (never dispatched) —

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

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: boucle:triage added / 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>-<slug>)
    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)

Entry is opt-in. An issue opened with no boucle: label does NOT enter the state machine: it has no boucle state at all, and the loop never touches it. A human hands it over by adding boucle:triage or by assigning the bot (BOT_JUST_ASSIGNED) — the two edges out of [*] above. Issues boucle opens for itself (schedules, triage sub-issues, the e2e follow-up) pass boucle:triage at creation, so they enter through the same edge as anything a human hands over. Setting BOUCLE_ENTRY_MODE=auto restores the legacy behaviour, where the issue opened webhook alone was enough — appropriate only for a tracker that exists for boucle and nothing else.

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.
<!-- boucle:needs-info v=1 reason=profile --> v=1 reason=profile lib/boucle-ci/triage.sh (first-issue profile determination, #186) lib/boucle-ci/triage.sh (jq filter, idempotency check) Marks the first-issue project-profile determination comment (detected infra on an auto/unset install). The human confirms by 👍/👎 reaction or a profile: site|infra reply; no agent run is burned while it waits.
<!-- boucle:profile-applied v=1 profile=infra --> v=1 profile=infra|site lib/boucle-ci/triage.sh (profile apply path, #186) lib/boucle-ci/triage.sh (jq filter, idempotency check) Marks the first-issue profile determination as applied (infra preset set, or site recorded). Once present, triage never re-posts a determination for the issue.
<!-- boucle:diagram-missing v=1 kinds=<kinds> --> v=1 kinds=<closed-set> gates.sh:169 (spec-completeness gate) gates.sh (re-trigger triage) Marks a spec that declares structural impacts (Size M/L) but is missing the required ## Diagram section. CI re-triggers triage to add only the missing diagram.
<!-- boucle:preview-missing v=1 kinds=<kinds> --> v=1 kinds=<closed-set> gates.sh:227 (spec-completeness gate) gates.sh (re-trigger triage) Marks a spec that declares visual impacts (Size M/L) but is missing the required preview.html / RENDER_REQUEST. CI re-triggers triage to add only the missing preview.
<!-- boucle:diagram-invalid v=1 rounds=<n> --> v=1 rounds=<n> or v=1 state=exhausted rounds=<n> gates.sh (check_diagram_syntax_gate) gates.sh (retry-bound count) Marks a spec whose Mermaid diagram the real parser rejects — the forge would render it as an error box. CI re-triggers triage to fix ONLY the diagram. After BOUCLE_DIAGRAM_SYNTAX_MAX_RETRIES rounds the marker carries state=exhausted and the spec goes to the human as-is instead of looping.

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 e2e.sh:179 Marks a final e2e verdict. Same SHA contract.
<!-- boucle:draft role=reviewer --> role=reviewer reviewer agent (first-pass draft) collapse-duplicate-notes:79, reviewer.sh:381 (promotion source) Draft reviewer verdict. Parser does NOT act; log-scraping promotes on step exhaustion.
<!-- boucle:draft role=e2e --> role=e2e e2e agent (first-pass draft) collapse-duplicate-notes:86, e2e.sh:187 (promotion source) Draft e2e verdict. Same as above.

3.4 Dependency / hierarchy markers

Marker Format Written by Parsed by Purpose
<!-- boucle:depends-on iids=N,M --> iids=<comma-separated-IIDs> triage.sh:755 (on each dependent sub-issue) bin/lib/depends-on.sh:38 (grep), dispatch.sh:427 (gate check) Declares sub-issue dependencies. Dispatch gates the worker until all dep IIDs are closed.
<!-- boucle:split-parent iids=N,M --> iids=<comma-separated-IIDs> triage (split operation) catchup.sh:66, doctor.sh:746, e2e.sh:75, triage.sh:518,520 (idempotency guard) Marks the parent issue of a split with its sub-issue IIDs. Used to cascade closure and detect duplicate splits.
<!-- boucle:blocked v=1 iids=N,M --> v=1 iids=<comma-separated-IIDs> dispatch.sh:461, boucle.sh:1136 (informational — marks the blocked note) Posted on a sub-issue blocked by open siblings. The label boucle:blocked is the state; this marker is the note's machine-readable header.
<!-- boucle:sibling-blocked v=1 sib=N --> v=1 sib=<active-sibling-IID> dispatch.sh:508, .gitlab-ci.yml:997 catchup.sh:86,94, e2e.sh:95,102 (jq parse) Posted when a sibling sub-issue is still active (working/review/approval). The issue starts automatically once the sibling reaches done/closed — sibling issues share the same domain and run one at a time to avoid merge conflicts.
<!-- boucle:unblocked v=1 by=N --> v=1 by=<closed-dep-IID> catchup.sh:100, e2e.sh:109 (informational — marks the unblock note) Posted when a dependency closes and the worker starts.
<!-- boucle:e2e-origin v=1 iid=N --> v=1 iid=<origin-IID> e2e.sh:267 (on follow-up issues) boucle.sh:705 (parse, to resolve the original issue from a follow-up) Carries the original issue IID on a follow-up issue created by e2e FAIL, so the loop can cascade back.
<!-- boucle:e2e-fail v=1 iid=N followup=M --> v=1 iid=<origin-IID> followup=<followup-IID> e2e.sh:291 (on follow-up issue created by e2e FAIL) (informational — links follow-up to origin) Posted on the follow-up issue created when e2e FAILs, linking it to the original issue for cascade.
<!-- boucle:e2e-escalation v=1 iid=N verdict=X --> v=1 iid=<IID> verdict=<uncertain|empty> e2e.sh:321,357 (on e2e UNCERTAIN or no-verdict) (informational — structured escalation) Posted when e2e escalates to human due to UNCERTAIN verdict or no verdict (step exhaustion). Records the verdict reason.
<!-- boucle:sub-issue v=1 --> v=1 triage (split operation) triage.sh:566 (skip in parent-body parsing) Marks a sub-issue body. Used to avoid parsing sub-issue content as parent-issue content.
<!-- boucle:recurring v=1 refs=N,M --> v=1 refs=<comma-separated-IIDs> triage agent (optional ## Recurring theme section) triage.sh (parse + label), worker.sh (inject refs as context) Recurring-theme declaration: flags the issue as part of a recurring class and cites prior closed issues. CI applies boucle:recurring (context tag surviving transitions). Worker receives prior-issue summaries to find the root cause. Non-blocking: never gates.
<!-- boucle:impacts v=1 kinds=... --> v=1 kinds=<comma-separated-kinds> triage agent (## Metadata section in the spec comment) triage.sh (parse_impacts_marker), gates.sh (check_diagram_gate, check_preview_gate) Structural/visual impact declaration (LESSONS.yml lesson #104): the triage declares which impacts this issue has from a closed set (architecture, data-model, process, state-machine, data-flow, deployment, ui, ux, design, none). CI cross-checks: a structural kind without a <!-- boucle:diagram v=1 --> marker → gate fails → triage re-triggered; a visual kind (ui/ux/design) without a preview.html + RENDER_REQUEST → gate fails → triage re-triggered. Drives the deterministic diagram/preview gate.
<!-- boucle:diagram v=1 types=... --> v=1 types=<comma-separated-Mermaid-block-types> triage agent (## Diagram section in the spec comment) triage.sh (parse_diagram_marker), gates.sh (check_diagram_gate) Diagram declaration: lists the Mermaid block types used in the ## Diagram section (e.g. erDiagram,flowchart). CI cross-checks this marker against the Impacts field of ## Metadata: a structural impact declared there without a <!-- boucle:diagram v=1 --> marker → gate fails → triage re-triggered. The Mermaid theme block (boucle.dev light/transparent) is defined in templates/diagram-theme.md — the static source of truth.
<!-- boucle:diagram-missing v=1 kinds=... --> v=1 kinds=<comma-separated-kinds> gates.sh:169 (check_diagram_gate) (informational — re-trigger note) Posted when a spec declares structural impacts (## Metadata) but lacks the required ## Diagram section. Triage is re-triggered to add ONLY the missing diagram — it must re-read its previous spec in the Prior discussion, not re-analyze from scratch.
<!-- boucle:preview-missing v=1 kinds=... --> v=1 kinds=<comma-separated-kinds> gates.sh:227 (check_preview_gate) (informational — re-trigger note) Posted when a spec declares visual impacts (## Metadata) but lacks the required preview.html / RENDER_REQUEST. Triage is re-triggered to add ONLY the missing preview — it must re-read its previous spec in the Prior discussion, not re-analyze from scratch.
<!-- boucle:diagram-invalid v=1 rounds=... --> v=1 rounds=<n> (+ state=exhausted once the bound is spent) gates.sh (check_diagram_syntax_gate) gates.sh (counts its own markers for the retry bound) Diagram SYNTAX verdict (LESSONS.yml lesson #109). bin/check-mermaid runs every ```mermaid fence in the spec through the real Mermaid parser; a parse error means the forge renders an error box instead of a diagram, so the gate blocks spec-review and re-triggers triage with the parser's own message. Fail-open when the parser is unavailable (no node, no modules, no network) — infrastructure never blocks the loop.

3.5 Operational markers

Marker Format Written by Parsed by Purpose
<!-- boucle:board v=1 --> v=1 boucle.sh:268 (status board body) (informational — identifies the board issue) Marks the status-board issue body. Dispatch skips boucle:board-labelled issues; this marker is the body's stamp.
<!-- boucle:catchup v=1 iid=N state=X target=Y --> v=1 iid=<IID> state=<from> target=<to> catchup.sh (audit note on direct merge) (informational — audit trail) Posted when an MR is merged directly (not via the approval flow). Records the state at merge time for audit. The target field is the terminal state the loop WOULD have applied pre-e2e-on-direct-merge; the actual terminal state is decided by the e2e verdict (PASS→done, FAIL/UNCERTAIN→human).
<!-- boucle:commit sha=<hex> --> sha=<short-sha> worker.sh:421-422 (in MR description + build marker) (preview freshness assertion — worker.sh) Anchors the MR/build to a commit SHA for preview freshness check (invariant I6-adjacent).
<!-- boucle:diagnostic v=1 iid=N class=X trigger=Y --> v=1 iid=<IID> class=<failure-class> trigger=<trigger> boucle.sh:475 (escalation diagnostic) (informational — structured escalation) Replaces the generic "human intervention needed" note with a structured diagnostic (failure class + evidence + recommended action).
<!-- boucle:schedule id=<name> --> id=<schedule-name> boucle.sh:201 (on scheduled issues) boucle.sh (dedup — last firing marker) Marks a scheduled issue with its template name. Used to prevent duplicate firings across sweeps.
<!-- boucle:state v=1 --> v=1 boucle.sh:436 (boucle_state_save, on worker exit) boucle.sh:462 (boucle_state_restore, on a cold state cache) Per-issue loop state (iteration log, approach, tried-and-rejected, last-outcome) persisted on the issue so it survives an ephemeral runner, where BOUCLE_STATE_CACHE does not. Collapsed, and excluded from the notes injected into agent prompts (bin/jc) so it is never re-billed as prompt input.
<!-- boucle:conflict-retry N --> N=<retry-count> boucle.sh:1099 (on re-trigger after rebase conflict) boucle.sh:1085 (jq parse, count retries) Posted on each re-trigger after a rebase conflict. Bounded retry count — after N retries, the conflict is handed to the worker agent for resolution.
<!-- boucle:file-blocked v=1 on=N paths=... --> v=1 on=<active-issue> paths=<overlap> gates.sh:106 (check_file_gate — defer on file overlap) gates.sh:192 (unblock path, last marker) The file-impact gate (LESSONS.yml lesson #62): posted when a worker would edit files claimed by an in-flight sibling issue. The unblock path fires when the named blocker closes.
<!-- boucle:files v=1 paths=... --> v=1 paths=<impacted-files> triage agent (embedded in the spec comment's ## Metadata section); worker job (lib/boucle-ci/worker.sh, refresh in a separate note after the branch diff) worker job (jq, find last marker note excluding the spec comment) File-impact declaration (LESSONS.yml lesson #62): the triage predicts the impacted files inside its spec comment, the worker refreshes the claim in a separate machine note with the actual branch diff. Consumed by check_file_gate to defer parallel workers on overlap.
<!-- boucle:evidence-pack v=1 --> v=1 bin/build-evidence-pack (header first line of the evidence pack) — Marks the auto-generated evidence pack (charter doc snapshot + diff brief) attached to escalations.
<!-- boucle:allow-list v=1 user=<username> --> v=1 user=<author-username> boucle.sh (check_allow_list_gate — rejection note) — Posted on an issue whose resolved human reporter is not in BOUCLE_ALLOWED_USERS. The issue is not accepted by the loop (no role triggered). Fail-open when the variable is unset (legacy).
<!-- boucle:interactive v=1 --> v=1 bin/boucle (cmd_pause, cmd_resume, cmd_restart — interactive harness) — Marks a comment posted by the interactive harness (boucle pause/resume/restart). Distinguishes a voluntary human takeover from a boucle:human escalation. Informational — dispatch does not act on it.
<!-- boucle:approval-request v=1 --> v=1 (no attrs) reviewer agent (posted on the PR via forge_mr_note when boucle_mono_user is true) doctor (jq: select(.body | contains("boucle:approval-request")), then forge_note_reactions polls for a canonical approval emoji) Mono-user PR approval gate: GitHub blocks self-review, so the reviewer posts this note on the PR and the human reacts 👍 to approve. The doctor's doctor_mr_approval_emoji polls the note's reactions and triggers the merger when a non-bot user reacted with a canonical approval emoji (👍 ❤️ 🚀 🎉). Replaces the old VERDICT: PASS auto-merge (no human signal).
<!-- boucle:opt-out v=1 --> v=1 (no attrs) dispatch.sh:929 (human label-removal webhook, #124) dispatch.sh:926 (idempotency — marker already present), doctor.sh:499 (unlabeled scan skip) Posted when a human removes the boucle:* labels (GitLab .changes.labels.previous / GitHub unlabeled event): the explicit "leave the loop" signal. Idempotent — later events no-op against it. The doctor's unlabeled scan skips tombstones so the issue is never re-appropriated; re-adding boucle:triage or assigning the bot re-enters the loop normally.

3.6 Markers NOT in code (do not emit)

Marker Status Note
(none currently) — Keep this table empty — a marker that is documented here but emitted by code FAILs bin/check-doc-sync.

3.7 Structural signals (not HTML comments)

Signal Format Parsed by Purpose
## TL;DR + ## Metadata two section headers in the same comment collapse-duplicate-notes:71-72, triage.sh (PRE_RUN_TRIAGE_ID / COMMENT filters) Structural final-comment detection for triage. A draft only has ## Metadata; a final has both ## TL;DR and ## Metadata. Defense-in-depth: even if the agent uses the wrong marker, the parser won't act on a draft that lacks ## TL;DR. Specs posted before the section merge carry a standalone ## Disposition instead of ## Metadata — the filters accept either.
## Parent issue\n#N section header + issue reference boucle.sh:699,768,774 (awk) Resolves the parent IID from a sub-issue body. Used by resolve_reporter_id, fetch-issue-attachments, maybe_close_parent.
## Depends on section header bin/lib/depends-on.sh:57,61 (awk fallback) Fallback parsing of dependencies when the <!-- boucle:depends-on --> marker is absent. Mirrors the ## Parent issue pattern.
## Approach section header in state.md worker.sh:482 (sed extraction), :551 (MR description) The worker's implementation approach, extracted from state.md into the MR description. The reviewer reads it to verify doc conformance.
VERDICT: PASS|FAIL|UNCERTAIN line-anchored (^VERDICT:) reviewer.sh:299,320,358,363; e2e.sh (same pattern) The verdict line. MUST be start-of-line anchored in greps (LESSONS.yml lesson #41) — an unanchored grep matches shell traces containing the substring.
BOT_JUST_ASSIGNED assignee-change detection dispatch.sh:504-539 The real "re-queue after boucle:human" mechanism (§4.1). Detected from .changes.assignees on the issue update webhook, not from a comment.
Emoji thumbsup heart rocket tada emoji award on a Note dispatch.sh (BOUCLE_SPEC_APPROVAL_EMOJIS="thumbsup heart rocket tada") Spec approval + needs-info re-trigger. Valid on an issue at boucle:spec-review (approve spec) or boucle:needs-info (re-trigger after action). MR approval is the native Approve button, NOT an emoji.
Emoji eyes (👀) emoji award on an Issue written by triage.sh (ack_issue_taken, BOUCLE_ACK_EMOJI="eyes"); discarded by dispatch.sh Bot → human acknowledgement: triage has picked the issue up. The only signal boucle writes as a reaction; deliberately outside the spec-approval set so it can never read as approval. Carries no routing meaning in either direction — dispatch skips issue-level 👀 events (§4.8).

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>-<slug> — re-review

A push to the worker branch (boucle/<iid>-<slug>) 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:

GitHub event + action GitLab action Routes to
pull_request synchronize update reviewer (§4.4)
pull_request closed, .pull_request.merged == true merge catchup
pull_request closed, not merged close §4.5
pull_request opened / reopened open / reopen §4.4
pull_request_review submitted, state approved approved merger (§4.3)
pull_request_review dismissed unapproved reviewer
any other review (commented, changes requested) (none) stays a note (§4.6)
ready_for_review, review_requested, edited (none) skip

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)

Filter Condition Action
boucle's own comment note body has <!-- boucle:agent --> marker skip (I7)
boucle's own 👀 ack emoji event, awardable_type == Issue, name canonicalizes to eyes skip
bot-originated event ACTOR == BOUCLE_BOT_USERNAME and action ≠ merge skip
system note object_attributes.system == true skip (AGENTS.md #34)
non-boucle branch source_branch does not start with boucle/<iid> skip

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.

Primitive Signature Effect
forge_issue_note <iid> <msg> post a comment on an issue (stamped <!-- boucle:agent -->)
forge_mr_note <mr_iid> <msg> post a comment on an MR (stamped)
forge_issue_labels_get <iid> read current labels (comma-separated)
forge_issue_labels_set <iid> <labels> write labels (replaces boucle: set, preserves non-boucle)
forge_issue_assign <iid> <user_id> assign the issue
forge_mr_diff <mr_iid> fetch MR diff
forge_mr_approvals <mr_iid> check native approval state
forge_mr_check_suites <mr_iid> fetch CI check suites
forge_trigger_role <iid> <role> [vars] trigger a role pipeline
set_boucle_label <iid> <detail> <gross> write detail+gross labels idempotently + reassign + notify

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>-<slug> (e.g. boucle/42-fix-nav-link). boucle_branch_name (lib/boucle.sh) derives the slug deterministically from the issue title: lowercase, kebab-case, max 40 chars, truncated at a word boundary when possible. The name MUST stay deterministic — same issue → same branch across iterations. When the title is empty or the fetch fails, the name falls back to the legacy bare boucle/<iid>.

boucle/<iid> remains the protocol key: every MR lookup (forge_mr_lookup_by_branch) prefix-matches on it, so an issue-title edit that changes the slug can never break a lookup (LESSONS.yml #70, #71).

The lifecycle:

  • Worker (CI, lib/boucle-ci/worker.sh) creates the branch from master/main, runs the agent, pushes, opens an MR targeting master/main. The agent does NOT create the branch.
  • 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 worker branch — bin/boucle pause prints its exact name — (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 it from master/main under the name bin/boucle pause prints.

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 (the origin site was 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.

8.0 The forge-native /boucle command

The /boucle command is a user-facing capability typed as an issue comment — a forge-native observability surface, distinct from the local bin/boucle harness below. It is read-only at MVP: no agent invocation, no label writes, no MR scope. It gives the human the one thing labels cannot carry: the content of an agent run and the detail of loop health, in the same channel the loop already posts in (I1, CONTEXT.md §7).

When to use it — you want to see what the agent did without leaving the issue; you want a quick health projection of the loop.

Trigger phrases (case-insensitive, anchored at the first non-empty line):

Trigger Verb Returns
/boucle log [role] log Tail of agent-output.log of the most recent run of <role> (default: the role in flight, else the last completed)
/boucle status status bin/health projection (iterations, outcomes by role, cost total, last verdict SHA, role in flight)
/boucle help help the verb list + the non-redundancy rationale
@<BOUCLE_BOT_USERNAME> log log same as /boucle log (equivalent trigger form)

What it does NOT do — no label changes (labels are control/state; /boucle is observability — never duplicate label control, I2), no agent invocation at MVP, no MR scope (issue comments only at MVP).

Authorization — log/status/help: actor ∈ {issue author, parent-issue human author via resolve_reporter_id, one generation}. These are observability of data the actor could already see in the CI UI — no new trust boundary. The future jc verb is maintainer-only. System notes filtered (lesson #34); closed-issue guard applies (except help, lesson #44).

Forge asymmetries — GitHub log is post-completion only (GitHub Actions has no streaming log API); the future tail live-log verb is GitLab-only. The post-completion log works on both forges.

Non-redundancy note — use labels for control; use /boucle for observability. NEVER use /boucle to write a label, and NEVER use a label to carry what /boucle observes.

Commands

The bin/boucle wrapper exposes eight verbs. Forge identity (project, host, forge type) is auto-detected from the origin git remote when CI vars are absent — see §Forge auth below.

Command Action
bin/boucle help Show usage with one-line description per command and examples. Also triggered by -h, --help, or no argument.
bin/boucle list [state] List open boucle issues from the forge, grouped by boucle state. Optional filter: list working, list human, list review… Alias: ls.
bin/boucle status <iid> Synthetic view: title, forge label, assignee, MR status, iteration count, state.md content, last 3 iterations. Works even without local .boucle-state/<iid>/.
bin/boucle check <iid> Pre-work gate check: file-gate (overlap with in-flight issues), dependency gate, sibling gate. Consultation only — informs, does not block.
bin/boucle log <iid> Prints .boucle-state/<iid>/agent-output.log (last run trace: tool calls, file reads, git operations).
bin/boucle pause <iid> Human takes over. Sets boucle:human, saves previous state, posts a comment.
bin/boucle resume <iid> Loop resumes. If the worker branch (boucle/<iid>-<slug>) has commits ahead → boucle:review (reviewer + merger). Otherwise restores the previous label.
bin/boucle restart <iid> Loop takes the issue from scratch (boucle:todo). Does not restore previous state.

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:

Excluded Role Local alternative
bin/describe-images Describe images via vision model The agent CLI reads the image directly with its Read tool (opencode supports vision)
bin/fetch-issue-attachments Download issue uploads glab api projects/:id/issues/<iid>/notes then glab api .../uploads/:secret/:filename (or gh api ...)
bin/fetch-mr-attachments Download MR uploads glab api projects/:id/merge_requests/<iid>/notes + download
bin/build-evidence-pack Extract charter docs + diff brief The agent CLI reads AGENTS.md, CONTEXT.md, LOOP.md, SKILL.md directly with Read
bin/render-preview Render preview HTML → PNG The agent CLI uses the browser tool (opencode browser) or screenshot
bin/collapse-duplicate-notes Dedupe bot notes Not needed in interactive mode (the human controls what they post)

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>.
Template Purpose
templates/triage.md Triage comment (marker + TL;DR, Diagram, Analysis, one ## Criteria section — acceptance, must-haves, non-goals —, Questions, and one collapsed ## Metadata section: impacts, impacted files, size, validation, disposition)
templates/verdict-reviewer.md Reviewer verdict (marker + VERDICT:)
templates/verdict-e2e.md E2e verdict (marker + VERDICT:)
templates/state.md state.md seed (Goal, Approach, Tried and rejected, Awaiting human)
templates/iterations.md iterations.md seed
templates/interactive-pause.md Comment posted by boucle pause
templates/interactive-resume.md Comment posted by boucle resume

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 the worker branch boucle/<iid>-<slug>
#    (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 the worker branch boucle/<iid>-<slug> (the name boucle pause prints), 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.

Failure mode Description Boucle detection Boucle recovery Lessons
Hard Agent crashes, times out, or the provider is down Empty agent log / no activity traces (is_api_down, exit 4) Fallback provider → human escalation #29, #30, #32
Silent Agent produces output but it is wrong, hallucinated, or a placeholder Reviewer verdict FAIL; log-scraping fallback finds no verdict Re-trigger worker with feedback; escalate on iteration cap #1, #2, #5, #46
Partial Agent exhausts step budget mid-draft (comment/verdict not posted) No posted note with final marker; draft marker found in stdout Log-scraping fallback promotes draft to final #1, #27, #45, #47
Contradiction Reviewer PASSes but human amendments are unaddressed Reviewer grades against frozen criteria, ignores amendments Feed amendments forward; reviewer MUST verify each amendment #16, #53
Cascade One role's bad output poisons downstream (stale preview, orphaned commit) Preview SHA mismatch; empty MR (commits_status) Re-trigger worker from preserved state; NEVER reset --hard a committed branch #21, #22, #51
Loop Rebase-conflict re-trigger never converges; doctor re-triggers a stuck issue <!-- boucle:conflict-retry N --> count; iteration cap Bounded retry → hand conflict to agent → escalate #43, #61, #63
Context Agent ignores instructions (context overload, lost state across iterations) state.md re-seeded; iterations.md absent Persist .boucle-state/ to $BOUCLE_STATE_CACHE; restore at startup #28

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:

State Boucle behavior Transition
CLOSED (normal) Primary provider runs the agent. Track failure via is_api_down / is_quota_exhausted. ≥1 failure (empty log, quota error) → OPEN
OPEN (failing) Do not call the primary. If BOUCLE_FALLBACK_PROVIDER is set, try the fallback model. If fallback also fails → human escalation. Fallback succeeds → HALF-OPEN; fallback fails → human
HALF-OPEN (testing recovery) Fallback run completed. Next run attempts the primary again. Primary succeeds → CLOSED; primary fails → OPEN

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).

Priority Agent Condition Boucle implementation
1 (primary) Full-capability model (e.g. deepseek-v4.1-flash) Default AGENT env var per role
2 (fallback) Fallback model on exit-4 Primary down / quota exhausted BOUCLE_FALLBACK_PROVIDER + BOUCLE_FALLBACK_MODEL_<ROLE> (lesson #30)
3 (degraded) Log-scraping fallback (post from stdout) Agent exhausted steps before posting bin/jc scrapes agent-output.log for drafted verdict/triage (lessons #27, #47)
4 (human) Human escalation All automated paths fail boucle:human + diagnostic comment (lesson #59)

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:

Gate Label Criterion Type
Spec review boucle:spec-review Triage validated spec (Size S) Blocking approval (human replies/emoji)
MR approval boucle:approval Reviewer PASSed Blocking approval (native Approve button)
Escalation boucle:human Iteration cap / UNCERTAIN / destructive Blocking review (human acts)
DND skip boucle:dnd (transient) DND window active Auto-skip with trace (lesson #47)
Autonomous skip boucle:autonomous (transient) Per-issue opt-in Auto-skip with trace (lesson #47)

9.5 Observability contract

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

Field Boucle source How to access
trace_id BOUCLE_ISSUE + BOUCLE_ROLE + pipeline ID CI variables
agent_id $AGENT (model name) env var
latency job duration CI job timing
input/output tokens agent stdout (if logged) agent-output.log
output posted comment / verdict forge API
confidence verdict (PASS / FAIL / UNCERTAIN) VERDICT: line
status success / failure / partial / escalated exit code + label transition
errors agent stderr + bin/jc diagnostics agent-output.log

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

04 同仓库更多 Skills

ankaboot-source
ankaboot-source/boucle

wrangler

Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

★ 2
ankaboot-source
ankaboot-source/boucle

web-design-guidelines

Web platform design and accessibility guidelines. Use when building web interfaces, auditing accessibility, implementing responsive layouts, or reviewing web UI code. Triggers on tasks involving HTML, CSS, web components, WCAG compliance, responsive design, or web performance.

★ 2
ankaboot-source
ankaboot-source/boucle

web-artifacts-builder

Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.

★ 2
ankaboot-source
ankaboot-source/boucle

wayfinder

Plan a huge chunk of work — more than one agent session can hold — as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.

★ 2
ankaboot-source
ankaboot-source/boucle

verification-before-completion

Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always

★ 2
ankaboot-source
ankaboot-source/boucle

ui-ux-pro-max

暂无简介

★ 2