feat(email-writing): define strict review contracts

[seonghobae]

Stack dependency

This Draft PR is stacked on #1322 (feat/inkspan-email-writing-guide) and implements Task 2 only from the committed LLM email-writing implementation plan. It deliberately excludes unrelated exploratory implementation changes.

Included

• strict backend request, response, diagnostic, selector, provenance, and feedback contracts;
• strict frontend response parser and Inkspan transport adapter;
• exact SHA-256 document revision and strong entity-tag validation;
• W3C TextPositionSelector transport using Unicode-code-point offsets;
• bounded JSON bytes, nodes, depth, arrays, objects, strings, and diagnostics;
• duplicate-key, malformed UTF-8, non-scalar Unicode, non-finite number, extra-field, coercion, and unsafe identifier rejection;
• privacy-minimized provenance containing only version/profile identifiers and hashes, never prompts, provider tokens, traces, source mail, or authored draft content;
• explicit incremental/deep review selector rules and applied-feedback revision rules;
• conversion into Inkspan diagnostics without adding semantic inference.

Semantic-authority boundary

These modules perform deterministic transport, integrity, size, and revision validation only. They do not decide whether prose is clear, polite, correct, technically suitable, actionable, or otherwise semantically acceptable. There is no keyword, regex, phrase-list, language-name, sender-domain, recipient-count, nearest-text, or positional fallback.

Customer next action

This PR is contracts only. Customers should continue to write and send email with the current editor and send path. No writing-guidance feature, language profile, or model is available in product. Writing and sending stay on the current path.

Exact-head verification

Previous head (stale body advertised b10f8dcc; live PR head before this merge):

c5fec3e5c4dc373f1b1d79d48b10ceffadf98f6b

Current head:

fb7c406ee1328a6ac42dbaf54bb6852c199d8b0a

Live parent #1322 (feat/inkspan-email-writing-guide) merged as the second parent:

bfc2df112136bb9fe358778d701e78bf9e78b685

Live protected develop contained in that parent:

dd8d15191338b841f9e6f3a06507c6a5643b95d0

Normal merge commit (not squash, not rebase, not force-push):

• first parent: c5fec3e5c4dc373f1b1d79d48b10ceffadf98f6b
• second parent: bfc2df112136bb9fe358778d701e78bf9e78b685

ADR numbering follows the live parent:

• calendar ADR-0004 stays unique (0004-status-weighted-calendar-conflicts.md from #1367);
• email-writing remains ADR-0005;
• Task 2 contract files were unchanged by the merge (no product conflict, no contract-semantics edit).

Local validation counts on fb7c406ee1328a6ac42dbaf54bb6852c199d8b0a:

• backend contract tests: 13 passed (test_email_writing_contracts.py + coverage + terminal-coverage)
• backend coverage: 100% (282 statements, 74 branches, fail-under=100)
• backend ruff: All checks passed
• frontend contract tests: 19 passed (3 files)
• frontend coverage: 100% statements 246/246, branches 163/163, functions 27/27, lines 204/204
• frontend typecheck: ok (tsc --noEmit)
• git diff --check on Task 2 contract files: ok
• conflict markers / product contract edits: 0

Predecessor evidence does not transfer. Checks, reviews, and security evidence recorded for b10f8dcc, c5fec3e5, 2f7b5780, or any earlier head are non-passing for this head.

Merge boundary

Keep this PR Draft while parent #1322 remains unmerged and the cross-repository release prerequisites remain unresolved. This PR does not add persistence, email/thread authorization, contextual-orchestrator transport, model calls, Judge calls, API routes, UI integration, publishing, or release changes. Independent review, branch protection, zero actionable threads, and exact-current-head required checks remain mandatory before merge. This update does not approve, merge, squash, empty-requeue, force-cancel, or mark Ready.

[coderabbitai]

Warning

Review limit reached

@seonghobae, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 34 minutes

Limit details: You’ve used all 1 included review currently available under your plan.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9d6e2c44-5ba2-4952-8c7e-3ae0c099c45d

📥 Commits

Reviewing files that changed from the base of the PR and between bfc2df1 and fb7c406.

📒 Files selected for processing (9)

• .github/workflows/email-writing-contracts-tdd.yml
• backend/services/email_writing_contracts.py
• backend/tests/test_email_writing_contracts.py
• backend/tests/test_email_writing_contracts_coverage.py
• backend/tests/test_email_writing_contracts_terminal_coverage.py
• frontend/src/lib/email-writing.coverage.test.ts
• frontend/src/lib/email-writing.parser-coverage.test.ts
• frontend/src/lib/email-writing.test.ts
• frontend/src/lib/email-writing.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

PR governance metadata gate is not ready for fb7c406ee1328a6ac42dbaf54bb6852c199d8b0a:

• Draft PR: merge automation is paused.

[seonghobae]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[seonghobae]

@coderabbitai review

Please review the unchanged exact current head fb7c406ee1328a6ac42dbaf54bb6852c199d8b0a (normal merge of live parent #1322 bfc2df11). Predecessor c5fec3e5 evidence does not transfer. Local Task 2: backend 13 passed / 100% coverage, frontend 19 passed / 100% coverage. Keep Draft. This comment is not an approval.

[coderabbitai]

@seonghobae I will review the current head fb7c406ee1328a6ac42dbaf54bb6852c199d8b0a. I will keep the PR in Draft. This request does not approve or merge the PR.

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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