chore(#812): WIP checkpoint — parked pending #789 terminal

docs/scratchpads/812-pr-review-comment.md

@@ -0,0 +1,49 @@
+# Issue #812 — durable Gitea PR review comments
+
+- **Lane:** ms-812
+- **Branch:** `fix/812-pr-review-comment`
+- **Issue:** mosaicstack/stack#812
+- **Budget:** 15K working estimate; single focused shell-wrapper/test/docs change.
+
+## Objective
+
+Make the Gitea `comment` action in `packages/mosaic/framework/tools/git/pr-review.sh` use tea v0.11.1's supported `tea comment` command and report success only after provider read-back verifies the created comment against the intended repository, PR, and exact body.
+
+## Plan
+
+1. Add and commit a failing shell regression harness before production changes.
+2. Verify RED against the nonexistent `tea pr comment` fallback false-positive.
+3. Implement the minimal supported write plus ID-based provider read-back.
+4. Document that wrapper write output is not durable provenance until read-back succeeds.
+5. Run focused regression tests, touched-package tests, and repository quality gates.
+6. Run independent review, remediate findings, queue-guard, push, and open a PR. Stop at PR-open for coordinator review/merge.
+
+## Progress checkpoints
+
+- [x] RED regression committed and reported to mosaic-100 (`3585cdfa`)
+- [x] Initial minimal fix implemented (`c3a83833`)
+- [x] Focused and package tests green after dependency build
+- [ ] Independent review passed
+- [ ] PR opened and reported with exact head SHA
+
+## Tests run
+
+- RED: `bash packages/mosaic/framework/tools/git/test-pr-review-gitea-comment.sh` failed against the old path because `tea pr comment` fell back and the wrapper returned success.
+- GREEN: all `packages/mosaic/framework/tools/git/test-*.sh` harnesses passed.
+- `pnpm build` passed (23/23 tasks).
+- `pnpm --filter @mosaicstack/mosaic test` passed (67 files, 1278 tests).
+- Package and root typecheck/lint/format gates passed.
+- Codex security review found no issues.
+- Codex code review requested changes: tea v0.11.1 has no supported `tea api`; replace read-back with the existing host-scoped authenticated curl/API path when work resumes.
+
+## Risks / blockers
+
+- **Coordination hold:** Mos directed #812 to remain parked until in-flight #789 reaches terminal state because #789 actively uses `pr-review.sh`. Branch must be pushed but no PR opened.
+- Initial implementation's `tea api` read-back is not compatible with tea v0.11.1 and must be remediated before PR.
+- Tea output shape must provide a created comment ID in JSON; failure to parse must fail closed.
+- Read-back must not accept a pre-existing comment with the same body.
+- Existing approve/request-changes behavior must remain unchanged and covered.
+
+## Final verification evidence
+
+Parked pending #789 terminal. No PR opened.