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

[ctwoodwa]

Summary

• Prose review pass (Stage 5) on Chapter 9 — The Local-First Practitioner Lens
• Trimmed from ~4,990 words to 3,818 words (target: 3,150–3,850)
• Advanced ICM marker from icm/prose-review to icm/voice-check

What was cut

• Global Deployment Context — dense regulatory enumeration condensed from ~350 words to ~150; the full coverage matrix pointer to Appendix F preserved
• What Changed Between Rounds — shared-device walkthrough tightened; step-by-step detail reduced without losing the substance
• Restatements throughout — removed sentences that restated the preceding sentence in every section
• Academic scaffolding — removed all "this section argues", "as noted above", and similar constructs
• Inline parenthetical expansions — cut repetitive acronym expansions (CRDT, SaaS, BYOC, etc.) after first use
• "Principle" section — cut the middle paragraph that restated the export-button argument already made in Act 1; preserved the opening and close

Test plan

• Word count: 3,818 (within ±10% of 3,500 target)
• ICM marker reads icm/voice-check
• No academic scaffolding phrases
• Two-act structure (R1 block → revision → R2 pass) preserved
• All eight checklist items in the practitioner checklist present

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Substantially rewrote foundational chapters with updated examples and clarified explanations of core concepts
  • Enhanced technical architecture documentation with detailed operational descriptions and component behaviors
  • Expanded practitioner guidance including backup/recovery workflows, governance models, and compliance checklists
  • Improved narrative flow and consistency throughout

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR substantially rewrites four dissertation chapters to strengthen narrative clarity and provide practitioner evaluation criteria. The changes clarify the SaaS failure model, define local-first ideals, detail the inverted-architecture layers, and add governance and production-readiness guidance. All changes are documentation-only with no exported-entity modifications.

Changes

Thesis narrative and architecture documentation revision

Layer / File(s)	Summary
SaaS failure model and problem statement vol-1/part-1-thesis-and-pain/ch01-when-saas-fights-reality.md	Opening establishes vendor-controlled infrastructure as the core failure point. The "Seven Ways SaaS Breaks" section (outage cascades, vendor disappearance, connectivity barriers, data export limits, pricing changes, silent corruption, third-party veto, deferred work) is rewritten with updated concrete examples and tighter language. Closing sections explain why users accepted SaaS constraints and position the inverted-stack model as removable.
Local-first ideals and solution taxonomy vol-1/part-1-thesis-and-pain/ch02-local-first-serious-stack.md	Defines seven local-first ideals and taxonomizes existing attempts (document sync, replica, offline finance, research prototypes). Reframes the ownership/collaboration tradeoff and the missing step of composing five components into a complete node. Concrete deliverables are specified: node architecture, CAP positioning, CRDT GC policy, key hierarchy, schema migration, enterprise deployment, and governance model.
Five-layer inverted architecture and failure modes vol-1/part-1-thesis-and-pain/ch03-inverted-stack-one-diagram.md	Re-authors the inversion thesis and five-layer stack: presentation (local-store rendering with health semantics and accessibility), application logic (local-first writes with CP-class lease coordination), sync daemon (peer discovery, gossip, delta streaming, Flease, write buffering), storage (SQLite+SQLCipher with CRDT documents, event log, projections), relay (ciphertext-only optional routing). Updates failure-mode exposition, explicitly defines Zone A (offline-by-default) and Zone C (multi-tenant per-host), and emphasizes local-first write success and explicit failure signaling.
Practitioner lens, export mechanics, and governance model vol-1/part-2-council-reads-the-paper/ch09-local-first-practitioner-lens.md	Adds practitioner review expanding Round 1→2 narrative: concrete export artifacts (JSON, per-tab CSVs, Markdown), detailed disaster recovery (single/shared-device recovery-code variants, BYOC selection), symmetric NAT + relay failure and self-hosted relay mitigation, and three-stage governance (BDFL→elected council→foundation). Reformats ideals compliance checklist with concise statements emphasizing "long now" retention and offline-first behavior. Expands observations on zero-state first-run risk, restore UX parity, accessibility, telemetry governance (opt-in disabled by default, aggregate-through-relay privacy model), and adds structured "Non-Negotiable Practitioner Checklist" anchoring data ownership on the export button and durable, restorable backup guarantees.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• Harborline-Software/the-inverted-stack#1: Both address the problem statement chapter (ch01), with this PR substantially rewriting that chapter to clarify the core SaaS failure model and examples.

Possibly related PRs

• Harborline-Software/the-inverted-stack#145: Both PRs modify Chapter 3 (ch03-inverted-stack-one-diagram.md), with overlapping rewrites of relay terminology, zone framing, and layer operational descriptions.

Poem

🐰 A thesis takes shape with each chapter refined—
From SaaS's sharp pain to the stack redesigned,
Five layers now gleam with their roles crystal clear,
And practitioners nod as the governance nears.
The inverted stack hops forward, no vendor in sight!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly describes the main change: a prose review pass advancing Chapter 9's status marker from prose-review to voice-check, with concise and specific phrasing.
Description check	✅ Passed	The PR description includes all required template sections: Summary (what was done, word count, ICM advancement), Type (Chapter prose), and Checklist (editorial conventions, no spoilers, canon updates). All sections are present and substantive.
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-ch09

---

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