Skip to content

Self-hosted project management for devs and their clients: tickets, time tracking, docs and meetings, with an AI assistant that cites its sources. AGPL-3.0.

Describe the comment format and its one rule in the maps

Guido Boyked2f9b65ec533
diff --git a/CLAUDE.md b/CLAUDE.md
index b962798..7f3e75e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -793,8 +793,10 @@ feature by feature):
`unauthorized`); an unmapped actor code is `refused` with the old value as `reason`. Every
body comes from `Api::V1::ErrorBody` through `BaseController#render_error`; guard
`spec/architecture/api_v1_error_body_guard_spec.rb`. Answers outside the controllers carry
- no `code`: the Rack::Attack 429 (plain text), a 500 from the exceptions app, and a 400 for a
- query string Rack cannot decode (`?x=%`; raised in middleware before any controller). The 401 of `/api/mcp` (same concern,
+ no `code`: the Rack::Attack 429 (plain text), a 500 from the exceptions app, a 400 for a
+ query string Rack cannot decode (`?x=%`; raised in middleware before any controller), and a
+ 400 for a parameter that is no valid UTF-8 (Rails raises `ActionController::BadRequest` while
+ it parses the parameters, which `BaseController` does not rescue). The 401 of `/api/mcp` (same concern,
`render_unauthorized`) keeps its old body.
* **`Idempotency-Key`** on every write (`idempotent :create` in the controller,
`Api::V1::Idempotent`): the same key and request replays the first 2xx answer (status and
@@ -827,6 +829,22 @@ by 50, at most 100; a value outside is a 400, never cut. Guards:
`spec/requests/api/v1/people_spec.rb`, `spec/requests/api/mcp_people_spec.rb`,
`spec/requests/api/people_parity_spec.rb` (REST and MCP answer the same rows).
+`POST /api/v1/tickets/:ticket_id/posts` (REST R3a) writes by the rule the MCP tool
+`post_comment` writes by, `Posts::Comment`, through `Actors::SavePost` like the web form:
+`post[format]` `html` (the default, the body stored as sent) or `plain` (literal text through
+`Posts::PlainTextBody`: escaped, blank lines into paragraphs, single breaks into `<br>`). An
+unknown format, one that is no string (read raw: strong parameters would drop a list and fall
+back to html), NUL in a plain body and a plain body that converts to nothing answer 422
+`validation_failed`/`invalid_input` with a text from `services.post_comment.*`, checked inside
+the read gate. Without `format` the answer stays byte for byte: an empty body is the model's
+refusal, after the write check, with every model message (the contract case `html_empty` was
+recorded before R3a). Invalid UTF-8 never reaches the rule over REST (the 400 above); MCP
+refuses it. An unexpected actor failure (`internal_error`) answers 500 without the exception's
+text, every other failure 422 `validation_failed` as before; MCP answers `comment failed:
+unexpected error`. Capability `posts.plain`. Guards:
+`spec/requests/api/v1/post_comment_format_spec.rb`, `spec/services/posts/comment_spec.rb`,
+`spec/requests/api/mcp_plain_comment_spec.rb`.
+
## Admin: Betreiber-Teile kommen nur über Schlitze
**Verbindlich** (Guard-Spec: `spec/architecture/admin_operator_boundary_guard_spec.rb`; läuft über
diff --git a/app/services/CLAUDE.md b/app/services/CLAUDE.md
index ac6a67c..bf1a45b 100644
--- a/app/services/CLAUDE.md
+++ b/app/services/CLAUDE.md
@@ -193,6 +193,14 @@ Verzeichnis-Übersicht (Auswahl):
`inbox_query.rb` + `serializer.rb`, der EINE Besitzer der Token-Inbox (Reichweite,
Argument-Vertrag, Zeilen-JSON), geteilt von `GET /api/v1/notifications` und dem
MCP-Werkzeug `list_notifications`
+* `posts/` — `comment.rb` (REST R3a, 29.10.2026) is the ONE rule of a comment written through
+ a token: the MCP tool `post_comment` and `POST /api/v1/tickets/:ticket_id/posts` call it.
+ `parse` (format `html`/`plain`, valid UTF-8, no NUL in plain, `plain_text_body.rb`, empty
+ after conversion), `build` (the unsaved post through `Actors::SavePost`, for the caller's
+ `:create?`), `save`; rights and wording stay with the callers. ⚠️ An empty html body is
+ answered differently on purpose: MCP refuses it before the ticket lookup (`body is
+ required`, as always), REST leaves it to the model after the write check (its answer
+ without `format` stays byte for byte). Not a second rule: do not align them in one hull.
* `lalabase/` — AI/RAG-Domäne (eigene Karte im Ordner)
* `access_check/` — Projekt-Zugriffslogik, 5 Objekte mit überlappenden Prädikaten —
**vor Neubau erst hier prüfen**. `project_access_service.rb` ist der EINE Besitzer der
diff --git a/app/services/lalabase/CLAUDE.md b/app/services/lalabase/CLAUDE.md
index 8d97736..2e66957 100644
--- a/app/services/lalabase/CLAUDE.md
+++ b/app/services/lalabase/CLAUDE.md
@@ -66,11 +66,13 @@ Codebase-Verständnis.
(default, unchanged ActionText input) or `plain`. `Posts::PlainTextBody` escapes
literal text, normalizes CR and CRLF, drops blank lines at the edges, turns blank
lines into paragraphs and single line breaks into `<br>`. Repeated spaces and
- indentation are stored but collapse in the web view; no Markdown. The tool checks
- the format itself (`FORMATS`), refuses invalid UTF-8 in either format and NUL in
- plain bodies as `invalid_input`, and decides emptiness on the converted text (a
- body of Unicode whitespace only is `body is required`); model save failures stay
- `refused`.
+ indentation are stored but collapse in the web view; no Markdown. The rule is
+ `Posts::Comment`'s since REST R3a, shared with `POST /api/v1/tickets/:ticket_id/posts`:
+ invalid UTF-8 in either format and NUL in plain bodies are `invalid_input`, emptiness
+ is decided on the converted text (a body of Unicode whitespace only is `body is
+ required`). The tool keeps its own texts (`REFUSAL_TEXT`) and checks before the ticket
+ lookup; model save failures stay `refused`, an unexpected one (`internal_error`) is
+ `comment failed: unexpected error`, never the exception's text.
Zwei Formen: `record`-Werkzeuge liefern
Zeilen und zitieren jede (Ticket-Werkzeuge), `report`-Werkzeuge liefern nur Zahlen und
zitieren die Auswertung (`summarize_time_sessions`, Zitationstyp `time_report`). Ein