Ticket schema

A ticket is a Markdown file whose YAML frontmatter (between --- delimiters) follows this contract. junco schema prints it as JSON Schema — this page renders the same data. The contract is additive-only: fields are added, never repurposed or removed, so external dispatchers can depend on it.

Flavor selection reads frontmatter in this order:

assess: present — audit ticket (parked findings, never a PR)
analyze: present — investigation ticket (parked comment draft)
repo: present — PR-flow ticket (worktree, agent, draft PR)
none of the three — Q&A ticket (read-only, answered in place)

junco schema

note — fields documented as worker-managed (retry_count, github:) are junco's bookkeeping. Dispatchers leave them alone; junco writes them.

Fields

`id`

string

Unique ticket identifier. Defaults to the filename (without .md) when omitted.

`repo`

string

Absolute path to the target git repo; presence makes this a PR-flow ticket, absence a Q&A ticket.

`priority`

low | normal | high

Scheduling priority. Defaults to normal.

`timeout_minutes`

number

Maximum execution time in minutes. Defaults to the daemon's configured default_timeout_minutes. Must be strictly positive; non-positive values fall back to the default.

`base_branch`

string

Base branch for the pull request. Defaults to the daemon's configured default_base_branch. Constrained to the git-ref charset so the value cannot smuggle a git option token.

`branch_name`

string

Explicit name for the feature branch. Defaults to a generated slug from the ticket id. Constrained to the git-ref charset so the value cannot smuggle a git option token.

`pr_title`

string

Pull request title. Defaults to the first H1 heading in the ticket body, or the ticket id.

`draft`

boolean

Open the pull request as a draft. Defaults to the daemon's configured draft_by_default.

`labels`

array

Labels to apply to the pull request. Merged with the daemon's configured default_labels.

`reviewers`

array

GitHub handles to request as pull request reviewers.

`amends_pr`

number

Pull request number to amend (push additional commits to) instead of opening a new PR.

`push_remote`

string

Git remote the PR flow pushes the feature branch to. Defaults to origin. Set to fork (with a fork remote configured on the clone) for fork-based PRs against repos the operator cannot push to; gh pr create then uses --head <fork-owner>:<branch>.

`not_before`

string

Do not claim this ticket before this UTC instant (ISO 8601). The worker sets this for retry backoff; dispatchers may also set it to schedule work.

`retry_count`

integer

Worker-managed: how many transparent requeue attempts this ticket has consumed. Do not set by hand.

`tools`

array

Tool allowlist override for this ticket's agent session. Q&A tickets default to a read-only subset (read, grep, find, ls); list tools explicitly (e.g. [read, grep, bash]) to opt in to more.

`workdir`

string

Q&A tickets only: directory the session runs in (read-only tools). Defaults to the worker's processing directory.

`network`

boolean

Sandbox egress opt-in for this ticket's agent session. Defaults to the configured `sandbox.network` policy (deny). Set true to allow network (e.g. installing a new dependency); only widens this one ticket.

`github`

object

Worker-managed: provenance of a ticket bridged from a GitHub issue. Do not set by hand — to request a linked issue on a local dispatch, see github_request.

github.nwo string: Repository name-with-owner, e.g. acme/api.
github.issue integer: Source issue number.
github.kind pr | ask | plan: Execution path.
github.external boolean: Worker-managed: true when the ticket targets a repo the operator does not control. The reporter posts no labels/comments to the upstream issue; the PR itself (from the push_remote fork) is the only outward-facing write.

`github_request`

object

Dispatcher-settable request: ask the worker to create a GitHub tracking issue for this ticket at claim time and link the resulting pull request to it (the PR body gains `Closes owner/repo#N`, so merging closes the issue). The worker creates the issue on the clone's origin repo under its own gh identity (the bot account when configured) and then stamps the worker-managed `github:` provenance block itself — dispatchers never write `github:` by hand. Best-effort: if the issue cannot be created (offline, no permission, non-GitHub origin) the ticket still runs, unlinked. Ignored on fork-push tickets (`push_remote: fork`), on amend tickets (`amends_pr` — the existing PR body is never edited, so the issue could never auto-close), and on Q&A/assess/analyze tickets.

github_request.create_issue boolean: Set true to request tracking-issue creation.

`assess`

object

Presence of this mapping selects the assessment flavor: junco audits the repository named in `repo:` (read-only agent session plus a dependency scan) and parks the findings for review instead of opening a pull request — nothing is filed until a human confirms the batch (`junco assess review` then `junco assess file`). Authored by `junco assess`.

assess.auto_plan boolean: Also apply the configured GitHub trigger label to each created issue, so the bridge plans it on its next sweep.
assess.issue integer: Issue-scoped audit: the audit is steered to the code this issue implicates, and filed findings carry a Context reference to it. Set by `junco assess owner/repo#N`.
assess.issue_title string: The scoping issue's title (machine-built, display-only).

`analyze`

object

Presence of this mapping selects the analysis flavor: junco investigates the issue named here against the repository in `repo:` and parks a comment draft for review — it never posts without operator confirmation. Authored by `junco analyze`.

analyze.issue integer: Issue number to investigate.
analyze.title string: Issue title, for display/logging.