docs(vol-1): ch06 prose review — advance to voice-check

[ctwoodwa]

Summary

• Prose review pass (Stage 5) on ch06-distributed-systems-lens.md
• Cut ~846 words (4,436 → 3,590); target was 3,150–3,850
• Advanced ICM marker from icm/prose-review to icm/voice-check

What was cut

• Regulatory acronym list (~350 words): collapsed the 20+ jurisdiction enumeration in the GC tier section to one sentence referencing Appendix F — the detail belongs there, not inline
• Restatement sentences: cut every sentence that repeated the preceding sentence's content
• Shevchenko intro: tightened from 3 paragraphs to 2; removed repetition of the "hidden complexity" framing
• YDotNet verification hedge paragraph: removed the "specification is complete, evidence catches up later" passage — it hedges the architecture's commitments and belongs in a footnote at most
• Filler transitions: cut "In a different category distribution that would have been..." and similar scaffolding

Style rules applied

Active voice, strong verbs; no hedging; no synonym cycling; no academic scaffolding; lead with punchline; cut restatement; paragraph length ≤6 sentences.

Test plan

• Word count: 3,590 (target 3,150–3,850)
• ICM marker advanced to icm/voice-check
• Two-act structure preserved (R1 block → revisions → R2 verdict)
• All five Round 2 conditions retained in the verdict list
• No <word>#<digit> patterns in commit body
• Commit type: docs

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Condensed and clarified chapters on SaaS reliability challenges and local-first architecture principles
  • Refined exposition of distributed systems correctness with more explicit, testable operational policies
  • Enhanced implementation-oriented descriptions and safety requirements
  • Improved overall readability and structural clarity throughout the documentation

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR substantially rewrites four dissertation chapters to tighten exposition, clarify architectural abstractions, and ground previously general claims in concrete specifications. The changes preserve core narratives while improving clarity: Chapter 1 condenses SaaS failure scenarios, Chapter 2 clarifies local-first definition and taxonomy, Chapter 3 refines the inverted-stack architecture model, and Chapter 6 specifies distributed-systems correctness policies.

Changes

Thesis Narrative Refinement

Layer / File(s)	Summary
SaaS Failure Modes vol-1/part-1-thesis-and-pain/ch01-when-saas-fights-reality.md	Chapter 1 opening Pune/Sunita scenario and pain-point sections are condensed for brevity while preserving thematic content: "Bundle Nobody Agreed To," all seven failure modes ("Outage," "Vendor," "Connectivity," "Data," "Price," "Drift," "Third-Party Veto"), audience asymmetry, and dependency sections are rewritten; footnote markers are added for sanctions/legal references; closing scenario reference changes from "Marcus" to "Sunita."
Local-First Definition and Taxonomy vol-1/part-1-thesis-and-pain/ch02-local-first-serious-stack.md	Chapter 2 clarifies "serious stack" definition via composition across deployment/security/governance; the seven properties and existing-approaches taxonomy (document-sync, replica/CRDT services, single-user finance, research prototypes) are reframed around where authority is held and where each approach fails; a new "What Each Gets Right" bridge explicitly states the vendor-independence vs team-collaboration tradeoff; "Full Node vs Smart Cache" is rewritten to enumerate local components and offline implications; "What This Book Adds" is restructured into explicit bullet-point contributions and clarified relay trust boundaries.
Inverted Stack Architecture vol-1/part-1-thesis-and-pain/ch03-inverted-stack-one-diagram.md	Chapter 3 refines the architectural inversion: relay behavior is clarified as optional with LAN-first, NAT-relay, offline, and deferred catch-up semantics; Layer 1 (presentation) is reframed as local-store rendering with sync-status and accessibility behavior; Layer 2 (application logic) is rewritten as network-free domain rules with unconditional CRDT writes except CP-class records consulting lease coordination; Layers 3–5 are updated with explicit peer-discovery tiers, gossip anti-entropy, encryption key derivation, keystore storage, and relay trust levels; failure-mode sections reorganize and reframe with updated examples; canonical shapes (Zone A/C) and developer implications are revised.
Distributed Systems Correctness Audit vol-1/part-2-council-reads-the-paper/ch06-distributed-systems-lens.md	Chapter 6 grounds abstract claims in concrete testable specifications: Act 1 Round 1 specifies explicit three-tier GC policy (ephemeral aggressive, business fixed-window, compliance no-GC) and reframes split-write gaps as correctness fences; Act 2 Round 2 adds Tier 3 GDPR Article 17 justification, detailed stale-peer snapshot-transfer recovery, expanded Flease split-write proof distinguishing mergeable vs non-mergeable CP operations, and bandwidth-throttled reconnection-storm handling; verdict-conditions list moves operation-validation guidance into a separate checklist; "Convergence Is Not Correctness" clarifies application-level invariant validation and quarantining; closing sentence emphasizes boundary-condition specification.

🎯 2 (Simple) | ⏱️ ~12 minutes

🐰 Four chapters dressed in prose so tight,
Pain points condensed, architectures bright—
SaaS failures, local-first vision clear,
Inverted stacks with safety frontier.
The thesis now speaks with concrete care! 🎓

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: a Stage 5 prose review pass on ch06 that advances the ICM marker to voice-check.
Description check	✅ Passed	The description is substantially complete, covering summary, type selection, detailed explanation of cuts and style rules applied, and a comprehensive test plan checklist with all items 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.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch prose/review-ch06

---

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