From fb79bff91feee1421bb1bed1d3119648691b208c Mon Sep 17 00:00:00 2001
From: Hermes Agent <hermes@web1.uscllc.com>
Date: Fri, 17 Jul 2026 11:24:46 -0500
Subject: [PATCH] =?UTF-8?q?chore(#812):=20WIP=20checkpoint=20=E2=80=94=20p?=
 =?UTF-8?q?arked=20pending=20#789=20terminal?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/scratchpads/812-pr-review-comment.md | 49 +++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 docs/scratchpads/812-pr-review-comment.md

diff --git a/docs/scratchpads/812-pr-review-comment.md b/docs/scratchpads/812-pr-review-comment.md
new file mode 100644
index 0000000..3a4437f
--- /dev/null
+++ b/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.