docs: add paperclips architecture comparison (refs #14)

tests/test_paperclips_analysis_doc.py

@@ -0,0 +1,62 @@
+import re
+from pathlib import Path
+
+DOC = Path('docs/paperclips-analysis.md')
+
+
+def read_doc():
+    assert DOC.exists(), f'missing doc: {DOC}'
+    return DOC.read_text(encoding='utf-8')
+
+
+def test_doc_exists():
+    assert DOC.exists(), f'missing doc: {DOC}'
+
+
+def test_doc_has_required_sections():
+    text = read_doc()
+    for heading in [
+        '# Universal Paperclips Architecture Comparison',
+        '## 15-Phase Progression Map',
+        '## 96-Node Project Dependency Graph',
+        '## Mathematical Formula Analysis',
+        '## Emotional Arc Analysis',
+        '## Lessons for The Beacon',
+    ]:
+        assert heading in text
+
+
+def test_doc_mentions_key_formulas():
+    text = read_doc()
+    required = [
+        'nextTrust = fibNext * 1000',
+        'creativitySpeed = Math.log10(processors) * Math.pow(processors, 1.1) + processors - 1',
+        'Math.pow((harvesterLevel + 1), 2.25)',
+        'golden ratio',
+        'quantum',
+    ]
+    for phrase in required:
+        assert phrase in text
+
+
+def test_doc_mentions_source_files_and_counts():
+    text = read_doc()
+    for phrase in [
+        'main.js (6499 lines)',
+        'projects.js (2451 lines)',
+        'combat.js (802 lines)',
+        'decisionproblem.com/paperclips',
+    ]:
+        assert phrase in text
+
+
+def test_doc_mentions_96_node_graph_and_15_phases():
+    text = read_doc()
+    assert '96-node' in text or '96 node' in text
+    phases = re.findall(r'^### Phase \d{1,2}:', text, re.MULTILINE)
+    assert len(phases) == 15, f'expected 15 phases, found {len(phases)}'
+
+
+def test_doc_is_substantial():
+    text = read_doc()
+    assert len(text) >= 4000