Agent policy for the issue tracker (.issuectl/AGENTS.md)

This is the policy file issuectl reads by convention. issuectl agents init created it, and issuectl doctor --fix regenerates only the block between the issuectl-managed sentinels at the bottom, from issues/.schema.yaml and .issuectl/transitions.yaml. The prose above the sentinels is ours to write and is kept in version control.

How to drive the tool is documented in the /issue skill that issuectl skill install puts into the harness, and every command describes its own flags with issuectl <command> --help --json. This file records only what neither of those can know about this repository. The top-level AGENTS.md covers the project as a whole and points here for issue policy.

Why the CLI, and not the editor, writes issue metadata

Every issue is a plain item.md under issues/<slug>/, so editing its frontmatter directly is easy and looks harmless. The write commands (set, update, apply, close, note, check, label, depend) exist because they take the repository write lock, validate against the schema and the transition rules, bump updated, stamp closed and closed_by on close, and return the version token that a later --expected-version uses to detect a lost update. A hand edit skips all of that without complaint; the file still parses, and the damage surfaces later as a doctor finding or a status the scheduling DAG misreads. The same applies to moving or renaming an issue directory: issuectl rename rewrites every reference to the slug, a manual mv leaves them dangling.

Body prose is different. The tool appends timestamped blocks only to ## Comments, ## Decisions, ## Agent Runs, and the ## Resolution that close --comment writes, so editing the rest of the body by hand or through issuectl body is fine. issuectl ready counts the checkboxes under ## Acceptance Criteria and ## Tests Run, so keep those as task lists. Planning documents (plan.md, analysis.md, validation.md, design.md, breakdown.md, todo.md) live in the issue directory next to item.md, which is why an issue directory is more than its frontmatter.

What issue state means in this repository

The open issues are the schedule, not a backlog. An open issue carries lane, lane_seq, and blocked_by so that issuectl dag can say what may run in parallel, and an open issue with no lane appears in the DAG as unscheduled. Labels classify content and nothing else. The deferred label that once meant "parked" was retired in favour of the deferred intake status with a deferred_until date; doctor flags the label if it reappears.

The DAG is also the release signal. The top-level AGENTS.md lets an agent decide a release on its own when the reservation-aware DAG is completely empty, and a crates.io publication cannot be replaced once made. So an open issue, laned or not, is what stands between a finished stint and an irreversible publication. That gives closing a weight it would not have in a tracker kept only for memory: close an issue when its work is done and verified, and leave it open when it is not, rather than tidying the DAG into emptiness.

Commits point at issues with a Refs-Issue: @<slug> or Fixes-Issue: @<slug> trailer, and issuectl sync-commits copies them onto the issue's commit list. On main its default range is empty, so it needs an explicit --range to record a commit that has just landed.

Transition rules

.issuectl/transitions.yaml is the source of the status graph the managed block summarizes, and it is meant to be edited. Its comments say why each edge exists: an in-flight issue does not drop back to untriaged, because that would silently un-work it, and an untriaged or parked item is dispositioned through issuectl intake, never quietly marked done or fixed. An illegal status change fails, and the message names the allowed sources; with --json the error carries the transition-illegal code and exits 2, and plain output exits 1. The answer is usually to go through the intermediate state or the intake command the rule points at, not to loosen the rule. note and check report the same mismatch only as a warning and still write, so a hard error reliably comes from a status change.

issuectl doctor --json is one of the repository's local checks listed in the top-level AGENTS.md, so it runs before any merge. It also checks that the managed block below matches the schema and transition files.

Schema-derived rules (generated)

Regenerated by issuectl doctor --fix. Do not hand-edit between the sentinels.

Frontmatter fields

• assessment_classification (optional, scalar)
• assessment_outcome (optional, scalar)
• assignee (optional, scalar)
• blocked_by (optional, list)
• closed (optional, scalar)
• closed_by (optional, scalar)
• collision (optional, list)
• created (optional, scalar)
• deferred_until (optional, scalar)
• disposition_note (optional, scalar)
• disposition_reason (optional, scalar) — allowed: by-design, out-of-scope, wontfix, withdrawn, superseded
• duplicate_of (optional, scalar)
• epic (optional, scalar)
• labels (optional, list)
• lane (optional, scalar)
• originating_run (optional, scalar)
• originating_run_kind (optional, scalar)
• owner (optional, scalar)
• priority (required, scalar) — allowed: low, normal, high
• provenance (optional, scalar)
• provenance_detail (optional, scalar)
• related (optional, list)
• reporter (optional, scalar)
• review_confidence (optional, scalar)
• review_severity (optional, scalar)
• review_source (optional, scalar)
• review_status (optional, scalar) — allowed: requested, in-review, approved, changes-requested
• review_target (optional, scalar)
• reviewer (optional, scalar)
• size (optional, scalar) — allowed: S, M, L, XL
• slug (optional, scalar)
• source_ref (optional, scalar)
• status (required, scalar) — allowed: open, in-progress, testing, untriaged, deferred, needs-info, done, fixed, wontfix, duplicate, cannot-reproduce, obsolete
• type (required, scalar) — allowed: bug, task, feature, improvement, chore, epic
• updated (optional, scalar)

Required body sections by issue type

No per-type body-section requirements declared.

Status-transition rules

• → cannot-reproduce
  • allowed from: untriaged, needs-info, deferred, open
• → deferred
  • allowed from: untriaged, needs-info, open
• → done
  • allowed from: open, in-progress, testing
• → duplicate
  • allowed from: untriaged, needs-info, deferred, open
• → fixed
  • allowed from: open, in-progress, testing
• → in-progress
  • allowed from: open, testing
• → needs-info
  • allowed from: untriaged, deferred, open
• → obsolete
  • allowed from: untriaged, needs-info, deferred, open
• → testing
  • allowed from: in-progress
• → untriaged
  • allowed from: needs-info, fixed, done, wontfix, duplicate, cannot-reproduce, obsolete
• → wontfix
  • allowed from: untriaged, needs-info, deferred, open, in-progress, testing