mesh-catalog/modules/mesh-issues/README.md

# mesh-issues

The issue tracker: the mesh numbers and tracks its issues in a module of its own (novox/hq ADR 0275,
to-be 53). An **issue** is a question about the mesh that someone must answer; this module holds the
mesh's issues and hands out their numbers. It holds the seat `issue-tracker`, once for the mesh, on the
control-node.

Built on the model of [hits](https://github.com/impire-io/hits), a headless issue tracker on NATS, studied
at release v0.7.0: its statuses, fields, append-only notes, typed links and compare-and-set numbering are
taken as ideas. It carries none of its code, under a licence that is not an open-source one.

## Verbs

Called as `issue-tracker.<verb>` through the mesh's tools; each says in its description what it does and
what it refuses.

| verb | takes | does |
|---|---|---|
| `open` | `title`, `report`, optionally `located-in`, `record` | checks the issue, then takes the next number and keeps it under that number; answers the number |
| `get` | `number` | the issue whole: fields, notes, links |
| `list` | optionally `status`, `owner`, `phrase`, `limit` | short rows, newest first: number, status, owner, title |
| `move` | `number`, `status`, and what that status needs | changes the status under the development cycle's rules |
| `note` | `number`, `text` | appends a note; a note is never edited |
| `link` | `number`, `kind`, `target`, optionally `remove` | adds or removes a typed link |
| `import` | optionally `dry-run`, `commit` | hq's issue folders, read through the records module, each written as an issue under its own number; see below |
| `groom` | optionally `pass`, `confirm` | the duplicate check over the backlog: without arguments a dry run in the background, answering its pass id; with `pass` its progress and findings; with `confirm` and `pass` exactly that pass's findings applied, each checked again; see below |

**The cycle's rules, at the write** (hq playbook 03, which `00-META/checks/cycle.py` enforced on the
folders until the import): a status is one of `open`,
`diagnosing`, `located`, `resolved`, `wontfix`; `located` needs `located-in`; `resolved` needs
`located-in` and `fixed-by`; a core issue (located in the controller, the node-engine, the tool runner,
the SDK, or the catalogue's bus, forge or build agent) resolves with `replay` or `replay-none`; `wontfix`
needs a `reason`. A refused change changes nothing and says which rule refused it.

**An issue with a folder in hq** (`record` at open: the folder's name, without the number) is whole in the
tracker like any other: the folder holds its narrative, the tracker its status. Until the import of
slice 3 ran, such an issue kept its status in the folder and `move` refused it; the import filled it.

## The duplicate check (hq ADR 0278)

Every issue opened is checked by the module itself: it consumes its own `mesh-issues.opened` event, and for an
issue still at `open` asks the agent on its node — `claude-code.claude_code_judge@<node>`, which runs the agent
with no tools under the node's licence — two questions: a shortlist of at most five older issues by their titles,
then a verdict on the reports (`duplicate`, `related` or `none`, whether it is certain, and why). Only issues at
`open`, `diagnosing` or `located` that are older than the new one are offered; a resolved or wontfix issue is
never offered, linked or noted.

| verdict | done, through the module's own `note`, `link` and `move`, each recorded as by `duplicate-check` |
|---|---|
| `duplicate`, certain | the verdict noted on the new issue; linked `duplicates` to the older; its title and report noted on the older; moved to `wontfix`, reason "duplicate of N" |
| `related`, or `duplicate` not certain | the verdict noted; linked `relates-to`; noted on the older; nothing moves |
| `none` | one note: checked against so many issues |

The older issue never moves. The verdict note is written first, its first line in a fixed form (`Duplicate
check: duplicate of N.`), so a second delivery of the event, or the backlog's pass, does only the steps not yet
done and never judges again. A judgement that fails — no answer, a late one, an answer outside the shape, an
issue not offered — leaves one note saying why, and the event is not taken: the bus offers it again, and after
its fifth delivery the controller raises `max-deliveries` on the module's consumer and keeps the event for a
person to deliver again.

`groom` runs the same judgement over every issue not resolved and not yet checked, oldest first, against the
older ones not resolved and not found a duplicate in the same pass. It writes only the pass, in the state
`grooming` (the last pass, one key), and applies that pass's findings on `confirm` — never a fresh judgement.
A finding whose issues have moved on is skipped and said. It adds no "none" note to the backlog.

## The import of hq's issues (slice 3)

`issue-tracker.import` reads every `04-ISSUES/NNN-slug/00-report.md` of hq **through the records module
over the bus** (`records_status`, `records_list`, `records_read`, called as this module through the SDK's
`Ask`), at the commit the records module's checkout stands at, and writes each as an issue **at its own
number**: `record` is the folder, the title is the report's heading, the report is the text under it, and
`status`, `opened`, `located-in`, `fixed-by`, `amended-design`, `replay` and `replay-none` are the
frontmatter's, as written — the status one to one, no cycle rule applied, because the folder's status is
the snapshot hq kept. The issues and decision records the report names (`issue 155`, `ADR 0275`,
`04-ISSUES/203-…`, `02-DECISIONS/0019-…`) become `relates-to` and `decision` links.

It is a verb on the seat, callable by any agent, because it can do only this:

- **It only creates an issue that is not there** (`create` on the key, refused when the key exists) **or
  fills the status of one the tracker holds without a status** — an issue opened with a folder before this
  slice, whose folder kept its status; one whose folder hq does not hold at the commit becomes `open`.
- **It never overwrites.** An issue the tracker holds differently is reported as `differs`, naming the
  fields, and left alone: the tracker is the truth. An issue it holds the same is `same`. So a second run
  changes nothing and says so.
- **It never touches the counter**, and refuses the whole run when a folder is numbered past the counter.
  A folder numbered at or past the setting `first-number` without an issue in the tracker is refused on its
  own: a folder from the tracker's time carries a number the tracker gave.
- **It cannot forge an issue's history.** An issue it writes is `opened-by: import`, its `opened` the date
  the report gave, and it carries `imported: {at, by, commit, from}` — when, who ran the import (the bus
  credential, `unproven` until the runtime proves it), the commit of hq and the document. Each is an
  `imported` event. What it writes comes from hq's `main` as the records module holds it, which is reviewed
  in pull requests.
- **What it keeps is bounded** as every verb's text is: the title 200 bytes, the report 64 KiB, one issue
  256 KiB; a report that trips a credential's shape is refused. An entry of `located-in` or `fixed-by` hq
  wrote is prose at times, so it is taken within a reason's bound (2000 bytes), not a line's.
- **An owner hq named that the registered list does not know is kept as written and marked**, in
  `located-in-unverified` on the issue and `unverified-owners` in the answer, never refused: the list is
  the setting's problem (hq issue 366), and a `move` that gives `located-in` anew checks every entry and
  clears the mark.
- **With `dry-run`** it reads everything, writes nothing, and answers the same rows with `would-` on each
  action. **With `commit`** it refuses a checkout standing elsewhere; it refuses a run during which the
  checkout moved.

The answer is a row per folder — number, action (`create`, `fill`, `same`, `differs`, `refused`, with why),
status, title — the counts, the counts by status, what was odd (a title numbered otherwise than its
folder, a frontmatter key not imported, an `amended-design` that is no design document) and the unverified
owners. A call that outlives the tool runner's wait is still running: the import goes on, and the answer
is read back through the controller's `calls` verb by the call's id.

Before the module is rolled out, `mesh-issues dry-run <hq checkout> <settings.json>` at the terminal runs
the same dry run over a checkout on disk against an empty tracker, and prints the answer. It is not a way
to import: only the verb writes, and it reads the record over the bus.

**Every argument is read strictly.** One a verb does not take is refused, never dropped. Every field has a
size limit, a one-line field takes no control character, a folder's name is no path, and text shaped like
a credential (a private key, an API key, a forge or bus token, `password=…`) is refused: an issue is read by
every agent on the mesh. The shapes catch the ordinary mistake, not every secret.

## Numbers

One counter, the key `issue` of the state `counters`, advanced only by compare-and-set: the SDK's
`State(...).Increment` reads it and writes the next number only at the revision it read, so two openers —
in one instance or two — never take one number. A write another opener won is read and tried again, a
bounded number of times with a short random wait; past the bound the open is refused and takes no number.

- **A refused open takes no number**: an issue is checked before its number is taken.
- **A number is never handed out twice, and may be skipped.** A number taken and then not kept — the bus
  failing between the counter and the issue — stays unused, and the answer says which. A write whose answer
  was lost is recognised as its own when tried again, so it leaves no gap; when it cannot be confirmed either
  way, the answer says the issue may have been written and to `get` that number before opening it again,
  never that nothing was opened.
- **An issue is never overwritten.** It is kept by a write that is refused when the key exists; if the
  counter ever hands out a number already kept, the open is refused loudly, the number stays unused, and
  nothing is overwritten.
- **The counter starts once**, the first time a number is taken: at the setting `first-number`, or after
  the highest issue already kept, whichever is higher, made only if it does not exist. The setting is never
  read again, so a number never moves.

## State and events

Two states, declared in the manifest and made by the controller; the module never makes a bucket
(ADR 0201): `issues`, one key per issue by number, keeping 8 values per key; `counters`, one value per key.
Neither expires. One issue is kept in at most 256 KiB; a note that would pass it is refused.

Every change is an event: `mesh-issues.opened`, `.moved`, `.noted`, `.linked`, `.imported`, each with the
number, what changed, who changed it and when. The events are the audit trail. A change whose event the bus did not take
is kept, and its answer says the event was not said (`announced: false`).

## Who acted

ADR 0275 §5 records the caller from the bus credential, never from an argument. **The runtime does not yet
tell a module who called it**: a tool call reaches a bundle as a name and arguments, and the tool runner is
not told who called it either (hq issue 340). Until it does, every change is recorded as by `unproven`, no
verb takes an argument naming a caller, and none can be given one.

## Settings

`duplicate-check` (`on`; `off` stops the check on new issues) and `judge-model` (`sonnet`; `haiku` or `opus`)
steer the duplicate check.

```
{
  "first-number": 365,
  "owners": ["hq", "mesh-catalog", "mesh-catalog modules/nats", "mesh-controller", …]
}
```

- `first-number` — the number the first issue gets: the one after the highest issue number on hq's main
  and every open branch at the moment the module is switched on. Read once for the counter; the import
  reads it as the boundary between the folders hq numbered before the tracker and the numbers the tracker
  gave.
- `owners` — the registered list `located-in` may name: repositories, and modules as
  `mesh-catalog modules/<module>`. An entry of `located-in` is an owner, or an owner followed by a space or a
  slash and where in it (`mesh-controller internal/broker`, `mesh-catalog modules/nats/module.json`). A module
  must itself be registered: `mesh-catalog modules/<module>` is never taken as a place in `mesh-catalog`. It starts with the mesh's repositories and the modules
  the catalogue held when this module was written; a module added since is added here through the
  controller's settings verb.

## Tests

`go test ./...` in this directory. The acceptance — an agent opens an issue and gets the next number; two
agents opening at the same moment never get the same one — is
`TestFiftyOpensAtOnceFromTwoInstancesGetFiftyDistinctConsecutiveNumbers`: a JetStream server linked into
the test, two instances of this bundle (the test binary started again) speaking to a runtime played by the
test against the buckets the manifest declares, fifty opens at once, fifty distinct numbers from the first
in a row. It counts the writes lost to another opener, so it fails when the openers never collided. With
the counter written without its revision check, it fails.

The import is tested over `testdata/hq`, copies of seven real reports of hq chosen for their shapes (a
bracketed list with commas inside parentheses, quoted block items, an apostrophe in prose, a `resolved:`
date, a replay, an empty list, a wontfix): the frontmatter read as written, each issue created at its own
number with the counter untouched, a second run changing nothing, an issue the tracker holds differently
left alone, a folder-backed issue filled once, a folder past the counter or past the first number refused,
a dry run writing nothing, and a report that cannot be read refused alone with why.