iris check --findings: every finding as JSON with a stable id

The id hashes scope, need, code and subject, nothing of the wording, so
the same gap keeps its id across runs. Every message that knows its fix
says it after "fix:". Codes listed in docs/lint.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/lint.md

@@ -50,6 +50,28 @@ already has the button, or the edge aggregates.yaml lacks. A schema
 error no longer hides the needs findings - both are printed, so one
 round can fix them together.
 
+`--findings <out.jsonl>` writes the same findings one JSON object per
+line: `id`, `level` (`fail`/`warn`), `code`, `scope` (`need`,
+`bucket`, or `repo` for a schema error), `need` (the need's id, or the
+bucket's name), `subject` (the state, the move as `from>to`, or the
+page), `message` and `fix`. The file is written empty when the content
+is clean. `id` hashes scope, need, code and subject and nothing of the
+wording, so the same gap keeps its id from one run to the next: a
+trainer can tell what a round closed, what is still open and what it
+broke. The codes:
+
+| code | |
+|---|---|
+| `schema` | content the site would refuse to load |
+| `need-duplicate`, `persona-unknown-need` | needs.yaml itself |
+| `entry-missing`, `entry-gated`, `entry-no-responsible` | the page a visitor arrives on |
+| `path-missing`, `path-closed`, `path-over-budget`, `path-no-action` | getting the answer recorded |
+| `machine-missing`, `desk-missing`, `desk-gated-twice` | who works the bucket |
+| `done-unknown`, `done-unreachable`, `success-not-done` | finishing a case |
+| `stage-unknown`, `stage-unreachable`, `stage-order` | the business's own stages |
+| `state-unreached`, `strand`, `edge-unoffered` | every state and move of the bucket |
+| `mail-unreachable`, `mail-unknown-field` | what a state mails |
+
 A need marked `planned` warns instead of failing. Exit status is the
 verdict, so a content repo's CI is one line.