[luv-343] docs: document per-CLI Stop semantics + Pi limitation

[NiveditJain]

Summary

Follow-up to #341. The Pi Stop-policy fix landed but it's a behavior end-users will see (Pi visibly stops, then the gate fires on the next prompt) — that's worth documenting up-front so a user enabling require-commit-before-stop on Pi understands the experience before filing a bug.

Adds a "Per-CLI Stop semantics" subsection at the top of the Workflow chapter in docs/built-in-policies.mdx:

• A 7-row table comparing Claude / Codex / Copilot / Cursor / Gemini / OpenCode / Pi — where the gate fires and what the user sees in each.
• A dedicated <Note> callout for Pi covering: why force-retry isn't possible (Pi's AgentEndEvent has no Result type — verified against pi-mono/packages/coding-agent/src/core/extensions/types.ts:1112), how the next-turn before_agent_start injection works, that the gate is one-shot per drain, and what the bounds are (Pi process lifetime; session_shutdown clears any pending entry for any reason).

No code changes — pure docs PR.

Files

• docs/built-in-policies.mdx — new "Per-CLI Stop semantics" subsection in the Workflow chapter (28 lines added).
• CHANGELOG.md — 0.0.10-beta.13 — 2026-05-10 Docs entry.

Translated copies under docs/{ar,de,es,fr,he,hi,it,ja,ko,pt-br,ru,tr,vi,zh}/built-in-policies.mdx will be regenerated by the translate-docs workflow when this lands on main.

Test plan

• <Note> open/close tag balance: 6 / 6 (matches existing file).
• No code changes — unit/e2e suites unaffected.
• CI: docs + quality + build all green.
• Spot-check the rendered page on Mintlify preview after merge.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Expanded workflow docs with a new “Per-CLI Stop semantics” subsection describing stop enforcement timing and user-visible behavior across supported CLIs (Claude, Codex, Copilot, Cursor, Gemini, OpenCode, Pi), including Pi’s next-turn directive and AgentEndEvent limitation.
  • Added a changelog entry documenting the documentation update.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b4075000-93a5-4c31-9c1e-1bf9f5bc2f4c

📥 Commits

Reviewing files that changed from the base of the PR and between 47b69ce and 40050c6.

📒 Files selected for processing (1)

• CHANGELOG.md

✅ Files skipped from review due to trivial changes (1)

• CHANGELOG.md

---

📝 Walkthrough

Walkthrough

This PR adds a “Per-CLI Stop semantics” subsection to the Workflow docs describing how Stop enforcement behaves across seven CLIs (Claude Code, Codex, GitHub Copilot CLI, Cursor Agent, Gemini CLI, OpenCode, Pi) and records the change in CHANGELOG.md (0.0.10-beta.13).

Changes

Per-CLI Stop Semantics Documentation

Layer / File(s)	Summary
Documentation Content docs/built-in-policies.mdx	New "Per-CLI Stop semantics" subsection under "Workflow" explains how Stop enforcement gates fire differently across Claude Code, Codex, GitHub Copilot CLI, Cursor Agent, Gemini CLI, OpenCode, and Pi. Includes a per-CLI behavior table and a detailed note on Pi's next-turn enforcement, one-shot in-memory deny draining, and session shutdown cleanup.
Changelog Entry CHANGELOG.md	Release notes for version 0.0.10-beta.13 (2026-05-10) document the Per-CLI Stop semantics documentation update in docs/built-in-policies.mdx.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• exospherehost/failproofai#341: Implements the Pi-specific next-turn Stop enforcement and timing behavior that this PR documents.

Poem

🐰 I hopped through docs at dawn’s first light,

Wrote how Stops behave in each CLI’s sight.
Seven gates, one table, Pi waits for the next turn,
In-memory denials drain, stale flags adjourn.
Hooray — the changelog now records our plight.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: documenting per-CLI Stop semantics and Pi's specific behavior limitation.
Description check	✅ Passed	The description is comprehensive and well-structured, covering the motivation, detailed changes, and test plan; however, the checklist items are not all marked complete.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CHANGELOG.md`:
- Line 6: Replace the placeholder "(`#PR`)" in the CHANGELOG.md entry that begins
"Per-CLI Stop semantics" with the actual pull request number (e.g. "(`#1234`)"),
ensuring the changelog line remains a single-line entry per project guidelines;
locate the string "(`#PR`)" in the CHANGELOG.md entry text and update it to the
real PR numeral so the release traceability format is preserved.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7912c1e1-0862-4d20-ba80-2237cde14633

📥 Commits

Reviewing files that changed from the base of the PR and between 462144d and 47b69ce.

📒 Files selected for processing (2)

• CHANGELOG.md
• docs/built-in-policies.mdx