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, and the numbers of decision and research records too (ADR
0275 rule 8, ADR 0290 rule 5). 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 (`by` for `diagnosing` and `fixing`, optionally `take-over`) | 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 |
| `set` | `number`, any of `severity`, `needs`, `suggested-owner` | changes them as a person decides |
| `groom` | optionally `pass`, `confirm` | the triage 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 |
| `tracking` | optionally `conditions` (condition keys) | for every condition key an issue links (link kind `condition`), the issues that link it, those not closed first: status, severity, needs, worker with since, active and stale, and where the fix is (`fix`); the operator's channel says it in a condition's message (hq ADR 0285) |
| `reserve` | `kind` (`decision` or `research`), optionally `for` (one line: what the record is about) | the next number of that kind, spent forever; answers `kind` and `number` (and `prefix`, the number as the record's name starts with it); 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, and hq ADR 0283): a status is one of `open`,
`diagnosing`, `located`, `fixing`, `resolved`, `wontfix`; `diagnosing` and `fixing` need `by`; `located` needs
`located-in`; `resolved` is reached only from `fixing` and 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.

**Who works on it** (hq ADR 0283). A move to `diagnosing` or `fixing` names in `by` the issue's **worker**: who
works on it and its node, as `who@node` (such as `fix-399@g14` or `jochen@shanks`, kept in lower case). The issue
keeps its worker (`worker`: `by`, `since`, `active`) while it stays at either status; any other status ends the
work. `get` shows it, with `worker-stale`, and each `list` row shows `worker`, `since` and `stale`. A move to either
status by someone else while the worker is current is refused, naming the worker; with `take-over` saying why, the
issue is taken over, and the reason is noted on it. A worker with no move, note, link or set from a caller on the
issue for `worker-stale-after` (default `24h`) is stale and may be taken over from without a reason, still noted.
The tracker's own writes (the triage, the duplicate check, the delivery notes) keep no worker current. The `moved`
event carries `by` (the worker; who acted, for a move naming none), `since`, `caller` (who acted, as the runtime
proves it: see *Who acted*), and `took-over-from`, `take-over` or `released` when they apply. `by` is what the
worker says it is, not who called, so the worker lets agents and people see each other; it is not a lock against
a false name.

**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 triage (hq ADR 0278, ADR 0279)

Every issue opened is triaged 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, always, a judgement on the reports: whether it repeats one (`duplicate`, `related` or `none`, whether it is
certain, and why), its **severity** (critical, major, minor), what it **needs** (none, decision, operator), a
suggested owner when it names none, and the shortlisted issues it **depends on** or **relates to**, each with a
one-line reason. Only issues at `open`, `diagnosing`, `located` or `fixing` that are older than the new one are offered.

The judgement is kept on the issue (`triage`) and said as the event `triaged` before anything else, then applied
through the module's own `note`, `set`, `link` and `move`, each recorded as by `triage` and each only when not
done yet:

1. one note saying the whole judgement, a line per value with its reason; where the issuer gave a severity or
   needs the triage disagrees with, the line says so and the given value stands;
2. each empty value filled — never one a person gave;
3. each `depends-on` and `relates-to` link added, unless it is there, would close a cycle, or its target is
   resolved or wontfix; the older issue gains a note;
4. a certain duplicate: linked `duplicates`, its title and report noted on the older, moved to `wontfix`
   "duplicate of N" last. The older issue never moves.

A second delivery of the event finds the kept judgement and finishes what is missing without judging again. A
judgement that fails leaves one note, and the event is not taken: after its fifth delivery the controller raises
`max-deliveries` on the module's consumer. Notes the duplicate check of ADR 0278 wrote as `duplicate-check` are
still read as that issue's verdict.

**Ready.** An issue is ready when it is not resolved or wontfix and every issue it depends on is wontfix, or
resolved with every pull request its `fixed-by` names (`<repository>#<number>`) delivered. The module consumes
`mesh-delivery.transition` and marks a pull request delivered on every issue naming it; at its own `moved` to
resolved it asks `seat:mesh-delivery.checks` once for what it has not heard. An issue made ready gains a note and
the event `ready`. `get` answers `waits-for`, `needed-by` and `ready`; `list` filters on `severity`, `needs` and
`ready` — an agent looking for work asks `severity=minor`, `needs=none`, `ready=true`. `set` changes severity,
needs and suggested owner as a person decides. `link` refuses a `depends-on` that would close a cycle.

`groom` triages every issue not resolved and not yet triaged, 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), each finding saying what applying it would do, and applies exactly that pass on `confirm`, each issue
checked again. One judgement runs at a time; the pass waits while a new issue's triage waits. A triage may take up
to two minutes, which the tool runner allows a handler while keeping its event alive (hq issue 387).

The new values are optional keys of an issue's one JSON value: an issue kept before reads as having none; the
key-value state has no schema to migrate.

## Whether the fix is delivered (hq ADR 0281)

For each pull request an issue's `fixed-by` names, the module keeps what `mesh-delivery.transition` last said —
state, why, merged and when — or asks `seat:mesh-delivery.checks` once (at its own `moved`) for one it has not
heard of. Nothing sets it by hand. `get` and every `list` row carry `delivery`, one line derived from it, worst
first: "fix not delivered: …", "held: …", "fix merged, not delivered: …", "fix not merged: …", "nothing heard from
the delivery of …", "delivered to every machine it should reach" (covered by a later merge says so).

Delivered is not resolved. When every fix of an issue not yet resolved is delivered, the issue gains a note and the
event `ready-to-verify`, once per set of fixes; it is resolved once its acceptance is proven live. A fix is named
while the issue stays `fixing`: `move` to the status it has changes what it holds and is refused when it changes
nothing.

Every five minutes the module looks for a fix merged and not delivered after `stuck-after` (default `2h`): it is
said once — a note on the issue and a warning on the operator's channel (`seat:operator-channel.notify`, key
`issue-tracker.fix-stuck.<number>`), cleared there when every fix of the issue is delivered. A module that runs only
its bundle cannot raise a controller condition (hq ADR 0240 rule 8, ADR 0256), so the warning is the channel's, not the controller's.

## 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 caller,
  as 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.

## Decision and research numbers

`issue-tracker.reserve {"kind": "decision"|"research", "for": "…"}` answers `{"kind": …, "number": N}` (hq
issue 424; the knowledge base asks it before it writes a record, ADR 0290 rule 5). Each kind has its own
counter beside `issue` in `counters` — keys `decision` and `research` — advanced the same way, so two
sessions writing a record at once never take one number.

- **A reserved number is spent forever**, whether or not its record ever lands; it is never handed out again.
  Each is kept in the state `reservations` under `decision-0292` or `research-046` with who reserved it
  (`by`, the caller as for every verb), when (`at`) and
  `for`, and said as the event `mesh-issues.reserved`. A reservation whose write cannot be confirmed is
  refused, and its number stays spent.
- **A refused reserve takes no number**: a kind other than `decision` or `research`, a `for` that is not one
  line of plain text or looks like a secret, an unknown argument.
- **A counter starts once**, at the first reserve of its kind, at the highest of: the numbers hq holds in
  `02-DECISIONS` or `01-RESEARCH` (read through the records module's `records_list` at its checkout, the
  number before the first `-` of each document or folder), the setting `decision-floor` or `research-floor`,
  and the reservations kept. The first number handed out is one above. Until hq can be read, the first
  reserve of a kind is refused and nothing is spent.
- **Never at or below a number hq holds**: each reserve reads hq again, and a counter that stands below the
  highest number there (one taken by hand) is raised to it first, written only at the revision read. When
  hq cannot be read once the counter has started, the counter is used as it stands, and the answer's
  `warning` says the number was not checked against hq.
- **Open branches are the floor's job.** The tracker reads hq's checkout of `main` and cannot list a folder on
  another branch with the forge tools it may call; a number taken on an open branch and not yet merged is
  covered by the floor. Before the first reserve of a kind, the operator raises `decision-floor` or
  `research-floor` (the controller's settings verb) to the highest number on any open branch of hq; once the
  counter has started, the floor is not read again.

## State and events

The 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
(`issue`, `decision`, `research`); `grooming`, the backlog's pass; `reservations`, one key per reserved number.
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`, `.reserved`, 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. **Who acted is the bus user
that called** (hq issue 365): a call on a tool's caller-named subject carries the caller's bus user as its last
token, the bus lets each user publish there with its own name alone, and the tool runner hands the module that
user from the subject the call arrived on (mesh-sdk `stdio.CallerOf`) — `shanks.node-tools` for an agent on
that machine's console, `person.<name>` for a person's credential. A call on the subject that names no caller
(served beside it for one release, hq issue 464), or through a runtime from before issue 365, is recorded as
by `unproven`. No verb takes an argument naming a caller, and none can be given one. The caller is only as sound
as the credential, which ADR 0266 keeps agents from reading (hq issue 333).

## Settings

`duplicate-check` (`on`; `off` stops the triage of new issues), `judge-model` (`sonnet`; `haiku` or `opus`) and
`forge-owner` (the forge's owner of the repositories `fixed-by` names, for asking a delivery) steer the triage;
`stuck-after` (`2h`) is how long a merged fix may take to be delivered before it is said.

```
{
  "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.
- `decision-floor`, `research-floor` — the highest decision and research numbers taken where the tracker cannot
  read, such as an open branch of hq (293 and 45 when this was written: 0293 on an open branch, 045 on main).
  Read once, when that kind's counter starts; see *Decision and research numbers*.
- `worker-stale-after` — how long an issue's worker stays current with nothing done on the issue (hq ADR 0283),
  as a duration; `24h` when empty.
- `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.

`reserve`'s acceptance — sessions reserving at the same moment never get one number, and the first is above
what hq holds — is `TestFortyReservationsAtOnceFromTwoInstancesGetFortyDistinctConsecutiveNumbers` on the
same bus, with the records module played by the test, and the tests in `reserve_test.go`: the start above
hq, the floor and the reservations kept, a counter behind hq raised, a refused reserve spending nothing,
the first reserve refused while hq cannot be read, and a reservation that cannot be kept leaving its number
spent.

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.