feat(pr-management): connect findings pane curation to render and polish review hooks

docs/setup/secure-agent-setup.md

@@ -40,6 +40,8 @@
     - [Term canonicalization](#term-canonicalization)
     - [Scoping and fail-closed gates](#scoping-and-fail-closed-gates)
     - [Trade-offs and runtime characteristics](#trade-offs-and-runtime-characteristics)
+  - [Review findings curation mod (Claude Code plugin / hook)](#review-findings-curation-mod-claude-code-plugin--hook)
+    - [Unsandboxed filesystem writes (`$.fs.write`)](#unsandboxed-filesystem-writes-fswrite)
   - [Sandbox-error hint hook](#sandbox-error-hint-hook)
     - [Why install it](#why-install-it)
     - [Why install it user-scope, not project-scope](#why-install-it-user-scope-not-project-scope-1)
@@ -2015,6 +2017,32 @@ static scope.
   guard against accidental leaks; inline environment variables passed to the command
   line (e.g. `MAGPIE_ALLOW_EMBARGO_TERMS=1 git commit ...`) are ignored by the hook.
 
+## Review findings curation mod (Claude Code plugin / hook)
+
+For Claude Code harnesses using the `magpie-pr-management` plugin, the review findings interactive pane mod ([`plugins/magpie-pr-management/hooks/review-findings.ts`](../../plugins/magpie-pr-management/hooks/review-findings.ts)) provides an interactive terminal overview of findings during PR review triage and synchronizes maintainer curation decisions directly to disk beside the findings file.
+
+### Unsandboxed filesystem writes (`$.fs.write`)
+
+As established in [`docs/when-to-use-mods.md`](../when-to-use-mods.md), Claude Code mod hooks run outside the container sandbox with direct user privileges.
+The review findings mod introduces the framework's first use of `$.fs.write` in a mod hook.
+
+- **Rationale**: The mod communicates maintainer curation decisions (action toggles, inline keep selections, and edited review bodies) to the downstream deterministic CLI tool (`pr-management code-review render`) running in subsequent skill steps.
+  Writing sidecars avoids spawning background daemons, opening IPC sockets, or modifying global environment state.
+- **Write boundaries and unsandboxed execution**: Because Claude Code mod hooks execute outside the container sandbox with user privileges, `$.fs.write` targets the host filesystem directly.
+  The write destination is the directory of the `--findings` path intercepted from the preceding `code-review disposition` command (typically the session or scratch directory).
+  Sidecar creation is strictly restricted to sibling files (`<file>.curated.json` and `<file>.curated.keep`) beside an existing findings file.
+  Invalidation markers update existing sidecar paths when curation is cleaned up or when findings become empty.
+  To prevent symlink traversal outside the intended directory, writes refuse to follow paths that exist as symbolic links or non-regular files.
+  The fixed `.curated.*` suffixes and existence precheck ensure executable scripts, dotfiles, or unrelated system files are never overwritten.
+- **Fail-open design and clean fallback**: Filesystem write operations are non-blocking and fail open.
+  If `$.fs.write` encounters permission errors, read-only volumes, or quota exhaustion, execution never halts or crashes.
+  Instead, the failure records `syncError` in state, displays an explicit warning in the interactive pane footer and `/magpie-findings status`, and invalidates partial sidecars on disk.
+  Downstream skill steps fall back cleanly to original findings and the interactive sequential text picker prompt.
+- **Self-invalidation lifecycle**: Because the Claude Code mod filesystem API provides no `remove` or `unlink` methods, sidecars manage their lifecycle via deterministic self-invalidation rather than file deletion.
+  The curated JSON payload embeds the active PR number and the source findings file's SHA-256 digest in a metadata envelope.
+  When a write fails, when findings become empty, or when a disposition re-run detects a mismatched PR number, the hook writes explicit invalidation markers to disk.
+  Downstream CLI tools (`render`) validate the PR number and source hash directly before loading `<file>.curated.json`, ensuring stale, orphaned, or invalidated curation files are refused or bypassed.
+
 ## Sandbox-error hint hook
 
 Companion to the *Sandbox-bypass visibility hook* above — a