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

[ctwoodwa]

Summary

• Prose review pass (Stage 5) on ch07-security-lens.md
• Trimmed from 4,567 to 3,392 words (target 3,150–3,850; within ±10%)
• Advanced ICM marker from icm/prose-review to icm/voice-check

What was cut

• Regulatory-regime laundry list in the Compromised Relay section (150+ words of jurisdiction enumeration moved to a single representative sentence pointing to Appendix F)
• Restatement loops in the send-tier filtering argument (the "receive-and-hide / trust the application" point appeared three times; now once)
• Opening intro redundancy (three intro paragraphs collapsed to four tighter ones)
• Defense-in-Depth layer descriptions in the closing section (retained in the checklist; removed from the narrative where they re-stated what the checklist already says)
• Parenthetical acronym expansions after first use (DEK, KEK, CRDT, CID defined once, then used without expansion)
• Scaffolding transitions and round-trip restatements between major sections

Style rules applied

Active voice, strong verbs, no hedging, no synonym cycling, no academic scaffolding, punchline-first, no paragraph longer than 6 sentences.

Test plan

• Word count within ±10% of 3,500 target (3,392)
• ICM marker advanced to icm/voice-check
• No <word>#<digit> patterns in commit body
• Commit type is docs

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated chapters on architecture principles, system design patterns, and security procedures with refined explanations and improved clarity.
  • Enhanced descriptions of system components, failure modes, deployment models, and key-management workflows.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR refines the narrative and technical articulation across four book chapters: three chapters in Part 1 (SaaS failure modes, local-first principles, inverted stack architecture) and one chapter in Part 2 (security incident response and requirements). All changes preserve structure and core concepts while tightening prose, updating examples, and clarifying causal arguments.

Changes

Book narrative: thesis through security

Layer / File(s)	Summary
SaaS failure modes and vendor lock-in dynamics vol-1/part-1-thesis-and-pain/ch01-when-saas-fights-reality.md	Chapter 1 opening vignette and "Bundle Nobody Agreed To" are reframed; "Seven Ways SaaS Breaks" sections (outage/SSO lockout, vendor shutdown, offline baseline, data inaccessibility, post-adoption pricing, silent divergence, external-authority custody) are rewritten with updated examples and causal chains; downstream sections ("Work That Doesn't Stop," "Who Pays the Most," "Why Users Have Accepted This," "Dependency That Looks Inevitable") adjust story details and tighten arguments for architectural inversion.
Local-first principles and existing implementations vol-1/part-1-thesis-and-pain/ch02-local-first-serious-stack.md	Chapter 2 refocuses Seven Ideals (instant reads, offline authority, CRDT convergence, long-horizon, structural security); rewrites taxonomy of document sync, replica apps, single-user offline, and CRDT prototypes to clarify production-deployment and collaboration gaps; consolidates "What Each Gets Right" summary; reframes "full-node" thesis as local composition (not smart cache); expands "What This Book Adds" with regulatory context and bullet list of concrete contributions (microkernel contracts, CAP positioning, CRDT GC, key hierarchy, schema migration, enterprise deployment, governance).
Inverted stack architecture model and failure-mode implications vol-1/part-1-thesis-and-pain/ch03-inverted-stack-one-diagram.md	Chapter 3 tightens "inversion in one sentence" and relay/LAN-fallback roles; rewrites Layers 1–5 (presentation as local-store-driven with no degraded mode, application logic with CRDT discipline and CP-class exception, sync daemon with peer discovery/anti-entropy/delta/leases, storage/key/merge, relay trust models with ciphertext-only default); updates failure-mode analysis (resolved/exposed/handled risks including endpoint compromise, schema migration, CRDT GC debt); refreshes Zone A/Zone C deployment descriptions and developer-habit bullets (local-first writes, network-independent correctness, explicit failure surfacing).
Security requirements and incident-response procedures vol-1/part-2-council-reads-the-paper/ch07-security-lens.md	Chapter 7 (Security Lens) clarifies Round 1 key-compromise gaps via four unanswered incident-response questions, then specifies Round 2 resolution: KEK regeneration, DEK re-wrapping, node-level revocation, relay broadcast, user notification with data-at-risk window. Updates four remaining conditions (supply-chain signing with reproducible builds/transparency, compromised relay/compelled access, physical memory-window mitigation via re-authentication, credential recovery and GDPR Article 17 crypto-shredding with metadata residue). Refines defense-in-depth four-layer model and send-tier filtering invariant; revises non-negotiable checklist (key-compromise testing, root key custody via HSM/ceremony, supply-chain transparency, ciphertext-only relay, artifact-based credential recovery, crypto-shredding for erasure).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Harborline-Software/the-inverted-stack#145: Updates terminology and zone naming (Anchor/Bridge → Zone A/Zone C) in ch03-inverted-stack-one-diagram.md, overlapping with this PR's narrative refinement of the same section.

Poem

🐰 A thesis stands clearer, from pain to solution bright,
Local-first principles now flow with focused light,
Five layers of architecture, inverted from the cloud,
Security procedures laid explicit, strong and proud.
No outage, no lock-in—just data close and real,
The book now tells its story with a sharpened zeal. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: a prose review pass on chapter 7 that advances the document's review stage marker.
Description check	✅ Passed	The description follows the template structure with Summary, Type, and Checklist sections completed; all required information is present and detailed.
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-ch07

---

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