Labels & markers
Every label Carol v0.1.22 creates or reads, and the hidden markers it writes into issue, pull request and comment bodies.
Carol v0.1.22
Carol creates the labels it needs in the same plan that first uses them. Markers are hidden HTML comments that give each item Carol writes its identity. How Carol uses them is on Internals.
Base labels
carol bootstrap creates these, and carol doctor checks they exist.
| Label | On |
|---|---|
zurdo:scope | The pinned scope issue |
zurdo:research, zurdo:grilling | Ticket issues, by type |
zurdo:epic | A PRD's epic |
zurdo:task | A PRD's task issues |
zurdo:pending-review | A passed task waiting on a [manual] sign-off |
zurdo:failed | A task that failed its last run |
ready-for-agent | A task with no Depends-on |
needs-triage | A hand-filed issue waiting for a person to route it |
needs-info | A hand-filed issue waiting on its reporter |
ready-for-human | A hand-filed issue with a work type and an area |
wontfix | A hand-filed issue that won't be done |
Labels added as needed
| Label | Added by | Means |
|---|---|---|
effort:<tier> | publish | The task's Effort |
area:<name> | triage | A path in the issue matched that area's globs |
priority:p0 … priority:p3 | propose | The phase's rank. A person's later choice is kept. One a bot set last, this App or an earlier one, is Carol's to rewrite. |
Engine loop labels
| Label | Set by | Means |
|---|---|---|
carol:proposed | propose | A phase proposal |
carol:accepted | An acceptor | Accept the proposal (gate H1), or let an agent research an open research ticket |
carol:specified | specify | The proposal's PRD pull request is open |
carol:ready | Not added by v0.1.22 | A state label on the epic. run and report remove it. |
carol:running | run | The epic's run has started |
carol:reported | report | The run's verdict is on the epic |
carol:waiting | Carol | Questions wait for an acceptor's answers |
carol:take-recommended | An acceptor | Take every recommended answer |
carol:changes-requested | Carol | An acceptor requested changes on the head commit |
carol:halt | Carol | Plan nothing more for this phase, proposal or ticket until a person removes it |
carol:signed | An acceptor | Sign the [manual] checks of a zurdo:pending-review task, with the evidence in a comment. report creates the label once a verdict names a sign-off. |
carol:agreed:provider, carol:agreed:consumer | A contract side's owner | That side agrees to the contract |
Carol counts carol:accepted, carol:take-recommended and carol:agreed:* only when an acceptor added them last. See Human gates.
Hidden markers
Carol writes each marker as an HTML comment in a body. <prd> is the PRD's repository path, and <slug> the initiative's directory name.
| Item | Marker |
|---|---|
| Scope issue | <!-- zurdo-github scope=<slug> --> |
| Ticket issue | <!-- zurdo-github scope=<slug> ticket=<name> --> |
| Contract issue | <!-- zurdo-github scope=<slug> contract=<name> --> |
| Epic | <!-- zurdo-github prd=<prd> epic --> |
| Task issue | <!-- zurdo-github prd=<prd> task=<task-id> --> |
| Sync comment | <!-- carol-sync prd=<prd> task=<task-id> run=<started_at> --> |
| Proposal | <!-- zurdo-github scope=<slug> proposal=<phase> --> |
| PRD pull request | <!-- zurdo-github scope=<slug> prd-pr=<phase> --> |
| Run pull request | <!-- zurdo-github scope=<slug> run-pr=<phase> --> |
| Design pull request | <!-- zurdo-github scope=<slug> design-pr=<phase> --> |
| Findings pull request | <!-- zurdo-github scope=<slug> findings-pr=<ticket> --> |
| Release pull request | <!-- zurdo-github scope=<slug> release-pr=<phase> --> |
| Phase-review pull request | <!-- zurdo-github scope=<slug> review-pr=<phase> --> |
| Verdict comment | <!-- zurdo-github prd=<prd> report=<started_at> --> |
| Follow-up issue | <!-- zurdo-github prd=<prd> followup=<task-id> --> |
| Digest issue | <!-- zurdo-github scope=<slug> digest --> |
| AI usage issue | <!-- zurdo-github usage -->, with one <!-- usage host=<host> --> section per machine |
| Questions comment | <!-- carol:ask --> |
| PRD review push comment | <!-- carol:h2 --> |
| Run review verdict | <!-- carol:h3 --> |
| Run report comment | <!-- carol:run-report -->, a summary, then Zurdo's report as JSON in a collapsed block |
The carol: comment markers open the comment's first line. A reply that quotes a questions comment carries carol:ask too, but not at its start, so it reads as the answer and not as a new question. A run review whose follow-up run failed is posted without carol:h3, so it never counts as a verdict. report reads the newest carol:run-report comment whose report names the phase's PRD. The formats are on Human gates and The engine loop.
Two more comment markers keep notices from repeating: proposal=<phase> specified, and unauthorised=<event> for a label added by someone who isn't an acceptor.
<!-- zurdo-github prd=docs/billing/prds/prd-01-invoices.md task=task-03 -->
Warning
Never copy a body Carol wrote into another issue. Two items with one marker make Carol refuse the plan (exit 4).
Next: Exit codes & environment