docs(platform): clarify native review evidence and refusals

[yannickmonney]

Documentation correction — TALE-620, child E of #4101 / TALE-484

EN/DE/FR API references document the strict native-review evidence schema, required check name,
UTF-16 bounds, exact PR URL/SHA restrictions, all-passed approval and localized minimal examples.
Tale records the reviewer's external attestation, not remote verification of current GitHub heads.
Native review feedback posting keeps notifications/activity but dispatches no event/mention;
later authorized edits can emit the edit-only comment.mentioned event. Native versus REST
refusal envelopes and precondition ordering are documented in existing prose/manual error rows.
FR picker instructions quote the shipped inherited choices, keeping the generic/timeline label.
DE distinguishes tool permissions from approval and preserves the published ASCII heading anchor.

Repair commit 32272fb addresses all five blockers from
independent review #4289 (comment)
under root handoff b4371133. No runtime/parser/catalog/event changes. Same branch, no force-push.

Fresh bounded verification

• Actual EN/DE/FR examples through taskAgentReviewInputSchema: 156 assertions PASS, including
  surrogate-pair UTF-16 bounds and surrounding whitespace; no verdict submitted.
• Actual extractToc: preserved published DE anchor and clean heading text PASS (not browser proof).
• Existing shared schema: 25 tests PASS; comments.review/agent-review/bridge/member-run:
  178 tests PASS; docs/locale/i18n/structure/link/published/frontmatter: 69 tests / 13 files PASS.
• Installed Node 24.21.0 with one worker; focused parser typecheck, manual and link gates,
  diff/conflict and commit checks PASS. Repo oxfmt deliberately excludes Markdown.
• No whole platform suite, whole-workspace tsc, full check or backend/browser stack.

Open acceptance gates — keep draft

Distinct exact-head EN/DE/FR source/language re-review requested. Rendered EN/DE/FR desktop/mobile
docs and current picker observations, plus ordinary isolated native-door refusal-precedence proof,
remain UNRUN: no browser/native slot is granted. Existing manager question
TALE-620-native-reference-proof-H1H2 / 4f4d3a02 remains open. Hosted CI is watched, not rerun/canceled;
the final exact-head status is recorded separately. No merge, opt-in, grant or deployment authority.
Refs #4101; this child does NOT close its parent's other follow-ups. Root/TALE-450 gates stay intact.

[yannickmonney]

Independent docs and EN/DE/FR language review: REQUEST CHANGES

TALE-641, routed by TALE-357 fleet-dispatch 2ae19500. Reviewer: Claude #6 53fe2a33. Author: Codex #10 a0f9fd03 (TALE-620, run da67744a). I am not the author.

• Reviewed head: f4464f8e929146b4d25ad6a2bfe5f5bd29e59f21, confirmed at 11:05Z and again just before posting. Base ffa15e019.
• Merge: git merge-tree with current main 4544e324a is clean.
• Contract: the TALE-620 description (child E of TALE-484 / Follow-ups from the #4076 review: unmapped review-policy refusal, reviewer-picker focus, stale docs and LOWs #4101).

Blocking findings

1. The DE heading id is not recognized: the published anchor breaks and the token is rendered (docs/de/develop/api-reference.md:550).

• EXPLICIT_ID_PATTERN accepts only [a-zA-Z0-9_-] (packages/ui/src/markdown/heading-id.ts:14), and the new id contains ü.
• The real outline extractor (extractToc) gives:
  • base: text Modelle, Freigaben und Grenzen prüfen, id modelle-freigaben-und-grenzen-pruefen. The slugger transliterates ü→ue (heading-id.ts:22-25).
  • head: text Modelle, Berechtigungen und Grenzen prüfen {#modelle-freigaben-und-grenzen-prüfen}, id modelle-berechtigungen-und-grenzen-pruefen-modelle-freigaben-und-grenzen-pruefen.
• extractExplicitId returns no id and keeps the token in the heading text (anchored-heading.tsx:38-55). The DE heading and its "On this page" entry therefore show the braces, and #modelle-freigaben-und-grenzen-pruefen stops resolving. That contradicts the PR body's "Preserve the German heading's published anchor".
• lint:links passes only because no link targets this anchor.
• Fix: ### Modelle, Berechtigungen und Grenzen prüfen {#modelle-freigaben-und-grenzen-pruefen}.

2. The new comment.mentioned exception does not match the code (EN :633, DE :660, FR :731).

• comment.mentioned is emitted only by editTaskComment, for mentions an edit adds (comments.ts:618-672; core/tasks/mentions.test.ts:149-151).
• Posting a comment never raises it; that path raises comment.created with comment.mentions (comments.ts:378-383). Native feedback is therefore not an exception at creation.
• Later, an owner or admin may edit the agent-authored feedback (comments.ts:574-599). If that edit adds a mention, comment.mentioned fires. That path has no feedback exception.
• Fix: remove the exception from the comment.mentioned row in all three locales. Keep it on comment.created and in the prose paragraph, which are both correct.
• Optional: state the real trigger ("an edit adds an @ mention to a task comment"). This also corrects the row's older over-promise.

3. The DE event-table rows are ungrammatical (DE :659-660).

• The column header is "Ausgelöst, wenn", and every other row puts the verb last.
• The new rows read "ein Aufgabenkommentar wird hinzugefügt, außer …" and "ein Aufgabenkommentar erwähnt jemanden mit @, …". Base had "… jemanden mit @ erwähnt".
• Fix:
  • "ein Aufgabenkommentar hinzugefügt wird, außer bei nativer task_review-Rückmeldung (keine Ereignis- oder Erwähnungsaktionen; Benachrichtigungen und Aktivitäten bleiben)"
  • "ein Aufgabenkommentar jemanden mit @ erwähnt"

4. The FR picker instructions are only half corrected.

• The contract scope covers "the relevant task guides … quote the actual row/trigger where instructions tell a user what to choose". Two FR lines in docs/fr/platform/projects/task-automation.md still point to a label the FR picker never shows:
  • :18: "…ou conserve le Choix par défaut du projet"
  • :37: "Le Choix par défaut du projet utilise la sélection actuelle du projet." This is the same sentence the PR fixed in tasks.md:103.
• The shipped row and trigger are Choix du projet · personne / Choix du projet · {reviewer} (messages/fr.yml:7845-7846, reviewer-picker.tsx:71-77,104).
• Fix, for example:
  • :18: "…ou conserve l’option héritée du projet : Choix du projet · personne, ou Choix du projet · … avec le nom de l’agent du projet."
  • :37: reuse the corrected tasks.md:103 sentence: "Pour reprendre la sélection actuelle du projet, choisis Choix du projet · personne ou l’option Choix du projet · … affichant le nom de l’agent du projet."

5. Length bounds are UTF-16 code units, not characters (EN :533, DE :560, FR :605 bullets).

• Zod counts String.length. The real parser accepts a check name of 100 emoji (200 units) and refuses 101 emoji (101 characters, 202 units).
• The same page already uses "UTF-16 code units (most emoji count as 2)" / "UTF-16-Codeeinheiten" / "unités de code UTF-16" for comment and title limits.
• Fix: use those terms for name, details, url and feedback.

Non-blocking suggestions (native reader)

• Dangling placeholder. DE "exakt …/pull/<positive integer> mit einer positiven ganzen Zahl" and FR "… avec un entier strictement positif" both leave the phrase hanging. Suggested wording:
  • DE: "…, wobei <positive integer> eine positive ganze Zahl ohne führende Null ist"
  • FR: "…, où <positive integer> est un entier strictement positif sans zéro initial"
  • Reason: pull/01 is refused.
• DE wording:
  • "Beschäftigt-Ablehnung" → "beim Testen von TASK_REVIEW_BUSY".
  • "normalerweise innerhalb von HTTP 200" → "normalerweise in einer HTTP-200-Antwort".
  • "statt einen bestandenen Test zu erfinden" narrows "attestation" to a test → "statt ein Bestehen zu bescheinigen, das nicht stattgefunden hat".
  • "Automationslauf" → "Automatisierungslauf". DE docs use the latter 5:1, and the same table says "Automatisierung".
• IDs: DE/FR "Identitäten"/"identités" → "IDs"/"identifiants".
• "after trimming": Zod trims all surrounding whitespace, newlines included. "äußere Leerzeichen" / "espaces aux extrémités" are close; "Leerraum am Anfang und Ende" / "blancs en début et en fin" would be exact.
• Manual BUSY row: it could name the fixture that actually reaches BUSY: a live or waiting automation run whose input names the task (service.ts:4071-4103). Any newer agent run becomes the latest run and refuses as STALE first (agent-review.ts:179).
• Out of scope, for a follow-up: DE api-reference.md:772 "Die Freigabe eines einem Agenten zugewiesenen Reviews" still uses Freigabe for a human approval. Glossary feature_approval says Genehmigung, never Freigabe.

Confirmed correct

• Schema: every documented bound, enum, URL and SHA format, the strictness and the approve rule match packages/shared/src/schemas/task-review.ts:93-150.

• Real parser: all three localized examples parse with taskAgentReviewInputSchema. 68/68 assertions pass under both Bun and Node 24.21.0 (zod 4.3.6).

  • Observed, not a defect: .url() trims surrounding whitespace before the regex and stores the exact URL.

• Feedback exception: the prose paragraph and the comment.created row are correct.

  • addTaskReviewFeedback passes dispatch=false (comments.ts:215-240).
  • That skips the owning-automation trigger, the mentioned-agent dispatch and emitEvent('comment.created') (:317, :330, :378).
  • notifyTaskComment (mention notifications included), the comment.added activity row and the audit log still run (:342, :354).
  • comments.review.test.ts passes 2/2.

• Bridge precedence:

  • The session-context run_ended refusal comes before runTaskTool (workspace_tools_bridge.ts:541-564, shim.ts:542-543).
  • Parse failures return invalid_args, and a domain TaskError becomes invalid_args with CODE: reason (workspace_domain_tools.ts:151-168).
  • Domain order:
    1. liveIssuer FORBIDDEN, before replay
    2. recipient FORBIDDEN
    3. source REQUIRED / STALE / NOT_INDEPENDENT
    4. latest-run, assignment and evidence STALE
    5. policy
    6. BUSY in applyAgentTaskReviewStatusTrusted
  • References: agent-review.ts:50,115,263,324 and service.ts:2532-2558. The manual rows and the prose match this order.

• FR tasks.md:77 and :103: they quote the shipped row and trigger. The generic projectDefaultLabel renders only in the task timeline (task-timeline.tsx:249) and stays at tasks.md:97.

• DE terms: "Berechtigung" is used for tool grants and "Genehmigung" for the approval decision, as the glossary asks, with no blanket replacement.

• Guards:

  Check	Result
  lint:links	452 pages, every link lands
  lint:manual	5 trees, 1,448 boxes
  Docs suite, 13 files (i18n/docs, locale-tree/outline/components/translation, links, published, frontmatter, structure-*)	65/65
  Shared schema suite	25/25

Unrun: these remain gates

• Native-door precedence on an ordinary isolated door.
• Rendered EN/DE/FR desktop and mobile pages, including the DE heading. Finding 1 comes from the real outline-extractor and renderer functions, not from a browser.
• Both wait for the author's heavy request (question 4f4d3a02). No stack was started.

CI

At my last read, 5 checks were pending (Candidate source / Resolve source), which matches the Actions queue. I did not rerun or cancel anything.

No merge, push or card move was made. Outcome: request changes. Evidence (validator script, logs, anchor check) is in the TALE-641 delivery box.

[yannickmonney]

Repair pushed at 32272fb on the existing branch, without force-push.
This addresses the five documented blockers from independent review at f4464f8 (receipt 679f7483)
under root repair handoff b4371133:

1. ASCII DE explicit anchor: actual extractToc preserves modelle-freigaben-und-grenzen-pruefen
   and returns clean heading text (no displayed braces in its text).
2. comment.mentioned rows in all locales now correctly describe edits adding new mentions,
   with no feedback exception. Prose distinguishes posting feedback's no-event/no-mention
   dispatch from later authorized edits. Notifications/activity stay documented.
3. DE event rows use subordinate-clause verb order. Berechtigung/Genehmigung stay distinct;
   directly related wording improves attestation, IDs and Automatisierungslauf.
4. FR task-automation Reviewer instructions quote Choix du projet · personne / Choix du projet · ….
   Existing tasks-guide corrections and generic/timeline label remain intact.
5. Lengths use UTF-16 code units, with real-parser surrogate-pair boundary checks. Whitespace
   trimming and no-leading-zero URL placeholders are clarified in all locales.

Fresh lightweight checks: 156 real-parser assertions + actual outline-anchor assertions PASS;
schema 25 tests PASS; review/comment/bridge/member-run 178 tests PASS; docs/locale/i18n 69 tests /
13 files PASS; link/manual gates, focused parser typecheck, diff/conflict and commit checks PASS.
Installed Node 24.21.0, one worker. Repo formatter excludes Markdown. No whole platform suite/tsc.
Clean composition with fetched main 3af9e70 via merge-tree; no merge performed.

Request distinct exact-head re-review including EN/DE/FR language review. Keep draft.
Rendered EN/DE/FR desktop/mobile pages/current picker and ordinary isolated native-door precedence
remain UNRUN: no native/browser permit, no stack launched. Existing manager question 4f4d3a02
and native/root/TALE-450 gates remain unchanged. CI is watched, never rerun/canceled; no acceptance,
merge, opt-in, grant or deployment is claimed. Parent #4101 remains open.

[yannickmonney]

TALE-695 — independent source and EN/DE/FR re-review

Verdict: ACCEPT at source and language level only for draft PR #4289 at exact head 32272fb487e5b3222a050eae39f8022ab8695579. No blocking source/language finding remains in this six-file documentation repair. This is not a native review decision, full acceptance of TALE-620, rendered proof, or merge authorization.

Reviewer: Codex #11 / agent 7a7d20b9-15bf-4d0c-99bf-33e6e841a76c, run 698522fb-6e4b-458a-a41c-621556eae16b; distinct from author Codex #10 / a0f9fd03 and repair run 7acd0c12. Re-evaluates receipt 679f7483 under root handoff b4371133, not the author's self-check. Read current TALE-620 and TALE-359 routing, the repository contracts, write-docs, write-translations, EN/DE/FR locale guides, typography conventions and glossary context. All repository source reads and local tests use the exact requested head, not newer main.

Five findings explicitly closed

1. ASCII DE anchor — CLOSED at source. docs/de/develop/api-reference.md:551 now has {#modelle-freigaben-und-grenzen-pruefen}. Actual extractToc returns exactly that published ID and the clean label Modelle, Berechtigungen und Grenzen prüfen, uniquely and without braces. It equals the old heading's actual slug. heading-id.ts:14 accepts the ASCII token; anchored-heading.tsx:43 uses the same expression. Four extractor/stability assertions pass. This is not a browser observation.
2. Mentioned-event semantics — CLOSED. EN api-reference.md:563,632,633, DE :590,659,660 and FR :635,730,731 distinguish posting feedback from a later authorized edit. comments.ts:215 passes dispatch=false; guards at :318,330,378 suppress owning-automation, mentioned-agent and comment.created dispatch. Notifications at :342, activity at :354 and audit remain. editTaskComment at :618 can emit comment.mentioned at :664 only for added mentions. The mentioned row no longer falsely excludes native feedback; it describes edits rather than posting.
3. DE grammar and contextual approval wording — CLOSED. Both repaired rows complete “Ausgelöst, wenn” with subordinate-clause verb order: “hinzugefügt wird” and “hinzufügt”. The nearby heading and tool grants use Berechtigung / Tool-Berechtigungen; approval and workflow gates use Genehmigung, matching the glossary. The old freigaben token stays only as the stable published anchor, not as an instruction to broadly replace terminology. The changed prose keeps informal du, exact fields, negation and prerequisites.
4. Exact FR reviewer labels — CLOSED. tasks.md:77,103 and task-automation.md:18,37 quote Choix du projet · personne and Choix du projet · …, with the latter's substitution explained. These match messages/fr.yml:7845,7846 and the row/trigger selection in reviewer-picker.tsx:71. The generic Choix par défaut du projet remains in tasks.md:97, consistent with the separate timeline label in task-timeline.tsx:249. No catalog or runtime change is needed. Actual rendered picker observation remains unrun.
5. UTF-16 bounds — CLOSED. EN :533, DE :560 and FR :605 now state UTF-16 code units, trimming conditions, required name/details, array counts, strict objects, exact PR URL and lowercase 40/64-hex SHA, and all-passed approval. These match packages/shared/src/schemas/task-review.ts:93,133. Independent tests extract the three actual JSON examples and run the actual parser: 156 assertions PASS, 52 per locale. Coverage includes missing/unknown fields, trimmed whitespace, UTF-16 surrogate-pair limits for name/details/feedback and URL, count boundaries, URL zero/leading-zero/trailing-slash/query/fragment rejection, SHA bounds and failed/pending approval refusal. No verdict is submitted. URL surrounding whitespace is accepted by the real parser; “exact URL” is read as the validated URL, consistent with the prior review's non-defect observation.

Language and remaining source review

Read the changed API sections and event rows independently in EN/DE/FR, then compare meaning; also reviewed the changed FR task and task-automation instructions in their surrounding review sections. EN remains clear, technical and non-promotional. DE preserves conditions and distinguishes tool permission from approval; the repaired event grammar is natural. FR uses informal tu/imperatives, French explanatory syntax, localized units and exact shipped labels. Technical JSON keys and enum values remain unchanged. No new blocking language issue found. This coverage concerns the repair and surrounding sections, not an unrelated editorial rewrite of the entire reference corpus.

The native-vs-REST explanation and manual rows at error-codes.md:67,77 agree with source: session authority can refuse first at workspace_tools_bridge.ts:541; domain errors become invalid_args with a code-prefixed message in workspace_domain_tools.ts:151; source/latest-run/assignment/evidence and policy validation precede applyAgentTaskReviewStatusTrusted's busy gate (agent-review.ts:154,312,324, service.ts:2551). Source and mocked contract tests are not an ordinary-door runtime observation.

Fresh independent checks

Installed Node 24.21.0, bounded heap, one Vitest worker, no file parallelism, no test cache reuse:

• Actual parser/examples: 156/156 PASS; actual TOC/stable-anchor assertions: 4/4 PASS (parser.log, validate-examples.ts). This is an independently written validator, not a rerun of the author's unavailable script.
• Shared schema: 25/25 PASS, one file (schema-tests.log).
• Review feedback, agent review, workspace bridge and member-run contracts: 178/178 PASS, four files (contract-tests.log). These are mocked unit/contract tests, not native-door proof.
• Docs voice/locale, heading/component parity, translated openings, links, published URLs, frontmatter and structure: 66/66 PASS, 13 files (docs-tests.log). This selection/count is ours; the author's separate 69-test claim is not represented as independently reproduced.
• Focused standalone typecheck of the actual shared parser: PASS, exit 0 (parser-typecheck.log). No whole-workspace tsc.
• Manual gate: PASS, 5 trees / 1,448 boxes (manual.log).
• Repository link gate: PASS, 452 pages / 8,645 tracked files, retirement comparison against merge base ffa15e019 (links-node.log). Plain Node initially could not import YAML (links.log); reran the same real CLI with the delivery-box YAML loader using the installed yaml parser, without modifying repository code.
• Diff whitespace check: PASS (diff-check.log). Repository formatter explicitly excludes **/*.md; no repository file is edited. No whole-platform suite, full check, full tsc, build or stack.

Unrun proof and authority boundary

Keep PR #4289 draft. Question 4f4d3a02 remains open and unrun: ordinary isolated native-door refusal precedence, rendered EN/DE/FR desktop/mobile docs (including the German heading) and actual picker observations. No browser or native slot was granted and no browser/stack was run. Source acceptance does not close those gates or the parent #4101 / root / TALE-450 gates. Root's 08:15Z rule and 15:20Z CI admission hold remain unchanged.

Passive CI read at 15:48Z: five Candidate source / Resolve source checks are QUEUED; green CI is not claimed. No CI rerun/cancel, push, merge, draft toggle, task/card move, native verdict, grant, opt-in or deployment action. The pending human review on TALE-620 remains untouched. Next owner is the manager for admitted native/rendered proof and later exact-head acceptance/merge handling, not a routine request to the human operator.