docs: ground paperclips epic tracker for #15

Merge PR #194: fix: resolve #192 — move dead code to docs/reference, fix GENOME.md

GENOME.md

@@ -0,0 +1,181 @@
+# GENOME.md — the-beacon
+
+> Codebase analysis generated 2026-04-13. Sovereign AI idle game — browser-based.
+
+## Project Overview
+
+The Beacon is a browser-based idle/incremental game inspired by Universal Paperclips, themed around the Timmy Foundation's real journey building sovereign AI. The core divergence from Paperclips: the goal is not maximization — it is faithfulness. "Can you grow powerful without losing your purpose?"
+
+Static HTML/JS — no build step, no dependencies, no framework. Open `index.html` in any browser.
+
+**6,033 lines of JavaScript** across 11 files. **1 HTML file** with embedded CSS (~300 lines). **3 test files** (2 Node.js, 1 Python).
+
+## Architecture
+
+```
+index.html (UI + embedded CSS + inline JS ~5000L)
+    |
+    +-- js/engine.js      (1590L) Core game loop, tick, resources, buildings, projects, events
+    +-- js/data.js        (944L)  Building definitions, project trees, event tables, phase data
+    +-- js/render.js      (390L)  DOM rendering, UI updates, resource displays
+    +-- js/combat.js      (359L)  Canvas boid-flocking combat visualization
+    +-- js/sound.js       (401L)  Web Audio API ambient drone, phase-aware sound
+    +-- js/dismantle.js   (570L)  The Dismantle sequence (late-game narrative)
+    +-- js/main.js        (223L)  Initialization, game loop start, auto-save, help overlay
+    +-- js/utils.js       (314L)  Formatting, save/load, export/import, DOM helpers
+    +-- js/tutorial.js    (251L)  New player tutorial, step-by-step guidance
+    +-- js/strategy.js    (68L)   NPC strategy logic for combat
+    +-- js/emergent-mechanics.js  Emergent game mechanics from player behavior
+
+    CI scripts (not browser runtime):
+    +-- scripts/guardrails.sh  Static analysis guardrails for game logic
+    +-- scripts/smoke.mjs      Playwright smoke tests
+
+    Reference prototypes (NOT loaded by runtime):
+    +-- docs/reference/npc-logic-prototype.js    NPC state machine prototype
+    +-- docs/reference/guardrails-prototype.js   Stat validation prototype
+```
+
+## Entry Points
+
+### index.html
+The single entry point. Loads all JS files, contains all HTML structure and inline CSS. Open directly in browser — no server required.
+
+### js/main.js — Initialization
+`initGame()` sets initial state, starts the 10Hz tick loop (`setInterval(tick, 100)`), triggers tutorial for new games, loads saved games, starts ambient sound.
+
+### js/engine.js — Game Loop
+The `tick()` function runs every 100ms. Each tick:
+1. Accumulate resources (code, compute, knowledge, users, impact, rescues, ops, trust, creativity, harmony)
+2. Process buildings and their rate multipliers
+3. Check phase transitions (Phase 1→6 based on total code thresholds)
+4. Trigger random events (corruption events, alignment events, wizard events)
+5. Update boosts, debuffs, and cooldowns
+6. Call `render()` to update UI
+
+## Data Flow
+
+```
+User clicks "WRITE CODE" / presses SPACE
+    |
+    v
+G.code += 1 (or more with auto-clickers, combos, boosts)
+    |
+    v
+tick() accumulates all passive rates from buildings
+    |
+    v
+updateRates() recalculates based on:
+  - Building counts × base rates × boost multipliers
+  - Harmony (Timmy's multiplier, Pact drain/gain)
+  - Bilbo randomness (burst/vanish per tick)
+  - Active debuffs
+    |
+    v
+Phase check: totalCode thresholds → unlock new content
+    |
+    v
+Event roll: 2% per tick → corruption/alignment/wizard events
+    |
+    v
+render() updates DOM
+```
+
+## Key Abstractions
+
+### Resources (10 types)
+- **code** — primary resource, generated by clicking and AutoCoders
+- **compute** — powers training and inference
+- **knowledge** — from research, unlocks projects
+- **users** — from API deployment, drives ops and impact
+- **impact** — from users × agents, drives rescues
+- **rescues** — the endgame metric (people helped in crisis)
+- **ops** — operational currency, from users
+- **trust** — hard constraint, earned/lost by decisions
+- **creativity** — from Bilbo and community
+- **harmony** — fleet health, affects Timmy's multiplier
+
+### Buildings (defined in js/data.js as BDEF array)
+Each building has: id, name, description, cost formula, rates, unlock conditions. Buildings include:
+- AutoCode Generator, Home Server, Training Lab, API Endpoint
+- Wizard agents: Bezalel, Allegro, Ezra, Timmy, Fenrir, Bilbo
+- Infrastructure: Lazarus Pit, MemPalace, Forge CI, Mesh Nodes
+
+### Projects (in js/data.js)
+One-time purchases that unlock features, buildings, or multipliers. Organized in phases. Projects require specific resource thresholds and prerequisites.
+
+### Phases (6 total)
+1. The First Line (click → autocoder)
+2. Local Inference (server → training → first agent)
+3. Deployment (API → users → trust mechanic)
+4. The Network (open source → community)
+5. Sovereign Intelligence (self-improvement → The Pact)
+6. The Beacon (mesh → rescues → endings)
+
+### Events (corruption, alignment, wizard)
+Random events at 2% per tick. Include:
+- CI Runner Stuck, Ezra Offline, Unreviewed Merge
+- The Drift (alignment events offering shortcuts)
+- Bilbo Vanished, Community Drama
+- Boss encounters (combat.js)
+
+### Endings (4 types)
+- The Empty Room (high impact, low trust, no Pact)
+- The Platform (high impact, medium trust, no Pact)
+- The Beacon (high rescues, high trust, Pact active, harmony > 50)
+- The Drift (too many shortcuts accepted)
+
+## API Surface
+
+### Save/Load (localStorage)
+- `saveGame()` — serializes G state to localStorage
+- `loadGame()` — deserializes from localStorage
+- `exportGame()` — JSON download of save state
+- `importGame()` — JSON upload to restore state
+
+### No external APIs
+The game is entirely client-side. No network calls, no analytics, no tracking.
+
+### Audio (Web Audio API)
+- `Sound.startAmbient()` — oscillator-based ambient drone
+- `Sound.updateAmbientPhase(phase)` — frequency shifts with game phase
+- Sound effects for clicks, upgrades, events
+
+## Test Coverage
+
+### Existing Tests
+- `tests/test_reckoning_projects.py` (148 lines) — Python test for reckoning project data validation
+- `tests/dismantle.test.cjs` — Node.js test for dismantle sequence
+
+### Coverage Gaps
+- **No tests for core engine logic** (tick, resource accumulation, rate calculation)
+- **No tests for event system** (event triggers, probability, effects)
+- **No tests for phase transitions** (threshold checks, unlock conditions)
+- **No tests for save/load** (serialization roundtrip, corruption handling)
+- **No tests for building cost scaling** (exponential cost formulas)
+- **No tests for harmony/drift mechanics** (the core gameplay differentiator)
+- **No tests for endings** (condition checks, state transitions)
+
+### Critical paths that need tests:
+1. **Resource accumulation**: tick() correctly multiplies rates by building counts and boosts
+2. **Phase transitions**: totalCode thresholds unlock correct content
+3. **Save/load roundtrip**: localStorage serialization preserves full game state
+4. **Event probability**: 2% per tick produces expected distribution
+5. **Harmony calculation**: wizard drain vs. Pact/NightlyWatch/MemPalace gains
+6. **Ending conditions**: each ending triggers on correct state
+
+## Security Considerations
+
+- **No authentication**: game is fully client-side, no user accounts
+- **localStorage manipulation**: players can edit save data to cheat (acceptable for single-player idle game)
+- **No XSS risk**: all DOM updates use textContent or innerHTML with game-controlled data only
+- **No external dependencies**: zero attack surface from third-party code
+- **Web Audio autoplay policy**: sound starts on first user interaction (compliant)
+
+## Design Decisions
+
+- **No build step**: intentional. Open index.html, play. No npm, no webpack, no framework.
+- **10Hz tick rate**: 100ms interval balances responsiveness with CPU usage
+- **Global state object (G)**: mirrors Paperclips' pattern. Simple, flat, serializable.
+- **Inline CSS in HTML**: keeps the project to 2 files minimum (index.html + JS)
+- **Progressive phase unlocks**: prevents information overload, teaches mechanics gradually

docs/DEAD_CODE_AUDIT_2026-04-12.md

@@ -3,20 +3,15 @@ _2026-04-12, Perplexity QA_
 
 ## Findings
 
-### Potentially Unimported Files
+### Dead Code — Resolved (2026-04-15, Issue #192)
 
-The following files were added by recent PRs but may not be imported
-by the main game runtime (`js/main.js` → `js/engine.js`):
+The following files were confirmed dead code — never imported by any runtime module.
+They have been moved to `docs/reference/` as prototype reference code.
 
-| File | Added By | Lines | Status |
-|------|----------|-------|--------|
-| `game/npc-logic.js` | PR #79 (GOFAI NPC State Machine) | ~150 | **Verify import** |
-| `scripts/guardrails.js` | PR #80 (GOFAI Symbolic Guardrails) | ~120 | **Verify import** |
-
-**Action:** Check if `js/main.js` or `js/engine.js` imports from `game/` or `scripts/`.
-If not, these files are dead code and should either be:
-1. Imported and wired into the game loop, or
-2. Moved to `docs/` as reference implementations
+| File | Original | Resolution |
+|------|----------|------------|
+| `game/npc-logic.js` | PR #79 (GOFAI NPC State Machine) | **Moved to `docs/reference/npc-logic-prototype.js`** — ES module using `export default`, incompatible with the global-script loading pattern. Concept (NPC state machine) is sound but not wired into any game system. |
+| `scripts/guardrails.js` | PR #80 (GOFAI Symbolic Guardrails) | **Moved to `docs/reference/guardrails-prototype.js`** — validates HP/MP/stats concepts that don't exist in The Beacon's resource system. The `scripts/guardrails.sh` (bash CI script) remains active. |
 
 ### game.js Bloat (PR #76)
 

docs/paperclips-implementation-tracker.md

@@ -0,0 +1,30 @@
+# Paperclips Deep Study — Implementation Tracker
+
+Grounded status snapshot for epic #15.
+This report tracks live forge issue state against visible repo evidence.
+It does not claim the epic is complete; it shows what is present vs missing today.
+
+- Forge issues: 8 open / 5 closed
+- Repo evidence: 8 present / 5 missing
+
+| Issue | Title | Forge state | Repo evidence | Proof |
+| --- | --- | --- | --- | --- |
+| #2 | [P0] Paperclips-style Project Chain System | open | present | js/data.js (`PROJECT DEFINITIONS (following Paperclips' pattern exactly)`, `const PDEFS = [`) |
+| #3 | [P0] Creative Compute (Quantum Burst System) | closed | present | js/data.js (`p_quantum_compute`, `Quantum-Inspired Compute`) |
+| #4 | [P0] Compute Budget Supply/Demand Momentum | open | missing | missing in js/data.js: `supply/demand`, `momentum` |
+| #5 | [P1] Strategy Engine Game Theory Tournaments | open | present | js/strategy.js (`Sovereign Strategy Engine`, `class StrategyEngine`) |
+| #6 | [P1] Community Swarm Alignment Simulation | open | present | js/data.js (`p_swarm_protocol`, `Every building now thinks in code.`) |
+| #7 | [P1] Fibonacci Trust Milestone System | open | missing | missing in js/data.js: `Fibonacci`, `trust milestone` |
+| #8 | [P1] Investment Engine Research Grants | open | missing | missing in js/data.js: `investment`, `research grant` |
+| #9 | [P2] Emotional Arc Milestone Narrative System | closed | present | js/emergent-mechanics.js (`THE BEACON - Emergent Game Mechanics`, `dynamic events that reward or challenge those strategies.`) |
+| #10 | [P2] Number Formatting spellf equivalent | closed | present | js/utils.js (`spellf()`, `one decillion`) |
+| #11 | [P2] Offline Progress Calculation | closed | present | js/render.js (`showOfflinePopup`, `Offline efficiency: 50%`) |
+| #12 | [P2] Prestige New Game+ System | open | missing | missing in js/data.js: `prestige`, `New Game+` |
+| #13 | [P3] Deploy Beacon as Static Site | closed | present | README.md (`No build step required`, `static HTML/JS game`) |
+| #14 | [P3] Paperclips Architecture Comparison Document | open | missing | missing in README.md: `Paperclips Architecture Comparison`, `architecture comparison` |
+
+## Notes
+
+- `present` means the repository contains directly relevant code or docs markers for that study item.
+- `missing` means the tracker could not find the expected markers yet; that child issue likely still needs a dedicated repo-side slice.
+- Because #15 is an epic tracker, this artifact should advance the issue with `Refs #15`, not close it.

scripts/paperclips_tracker.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""Generate a grounded implementation tracker for the Beacon Paperclips study epic."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+from typing import Iterable
+from urllib.request import Request, urlopen
+
+API_BASE = 'https://forge.alexanderwhitestone.com/api/v1'
+REPO = 'Timmy_Foundation/the-beacon'
+EPIC_NUMBER = 15
+TRACKED_ISSUES = [
+    {
+        'number': 2,
+        'title': '[P0] Paperclips-style Project Chain System',
+        'evidence': {
+            'path': 'js/data.js',
+            'snippets': [
+                "PROJECT DEFINITIONS (following Paperclips' pattern exactly)",
+                'const PDEFS = [',
+            ],
+        },
+    },
+    {
+        'number': 3,
+        'title': '[P0] Creative Compute (Quantum Burst System)',
+        'evidence': {
+            'path': 'js/data.js',
+            'snippets': [
+                'p_quantum_compute',
+                'Quantum-Inspired Compute',
+            ],
+        },
+    },
+    {
+        'number': 4,
+        'title': '[P0] Compute Budget Supply/Demand Momentum',
+        'evidence': {
+            'path': 'js/data.js',
+            'snippets': [
+                'supply/demand',
+                'momentum',
+            ],
+        },
+    },
+    {
+        'number': 5,
+        'title': '[P1] Strategy Engine Game Theory Tournaments',
+        'evidence': {
+            'path': 'js/strategy.js',
+            'snippets': [
+                'Sovereign Strategy Engine',
+                'class StrategyEngine',
+            ],
+        },
+    },
+    {
+        'number': 6,
+        'title': '[P1] Community Swarm Alignment Simulation',
+        'evidence': {
+            'path': 'js/data.js',
+            'snippets': [
+                'p_swarm_protocol',
+                'Every building now thinks in code.',
+            ],
+        },
+    },
+    {
+        'number': 7,
+        'title': '[P1] Fibonacci Trust Milestone System',
+        'evidence': {
+            'path': 'js/data.js',
+            'snippets': [
+                'Fibonacci',
+                'trust milestone',
+            ],
+        },
+    },
+    {
+        'number': 8,
+        'title': '[P1] Investment Engine Research Grants',
+        'evidence': {
+            'path': 'js/data.js',
+            'snippets': [
+                'investment',
+                'research grant',
+            ],
+        },
+    },
+    {
+        'number': 9,
+        'title': '[P2] Emotional Arc Milestone Narrative System',
+        'evidence': {
+            'path': 'js/emergent-mechanics.js',
+            'snippets': [
+                'THE BEACON - Emergent Game Mechanics',
+                'dynamic events that reward or challenge those strategies.',
+            ],
+        },
+    },
+    {
+        'number': 10,
+        'title': '[P2] Number Formatting spellf equivalent',
+        'evidence': {
+            'path': 'js/utils.js',
+            'snippets': [
+                'spellf()',
+                'one decillion',
+            ],
+        },
+    },
+    {
+        'number': 11,
+        'title': '[P2] Offline Progress Calculation',
+        'evidence': {
+            'path': 'js/render.js',
+            'snippets': [
+                'showOfflinePopup',
+                'Offline efficiency: 50%',
+            ],
+        },
+    },
+    {
+        'number': 12,
+        'title': '[P2] Prestige New Game+ System',
+        'evidence': {
+            'path': 'js/data.js',
+            'snippets': [
+                'prestige',
+                'New Game+',
+            ],
+        },
+    },
+    {
+        'number': 13,
+        'title': '[P3] Deploy Beacon as Static Site',
+        'evidence': {
+            'path': 'README.md',
+            'snippets': [
+                'No build step required',
+                'static HTML/JS game',
+            ],
+        },
+    },
+    {
+        'number': 14,
+        'title': '[P3] Paperclips Architecture Comparison Document',
+        'evidence': {
+            'path': 'README.md',
+            'snippets': [
+                'Paperclips Architecture Comparison',
+                'architecture comparison',
+            ],
+        },
+    },
+]
+
+
+def load_issue_states(issues_json: str | None) -> dict[int, dict]:
+    if issues_json:
+        records = json.loads(Path(issues_json).read_text(encoding='utf-8'))
+        return {int(record['number']): record for record in records}
+
+    token_path = Path(os.path.expanduser('~/.config/gitea/token'))
+    token = token_path.read_text(encoding='utf-8').strip()
+    headers = {'Authorization': f'token {token}'}
+    states = {}
+    for issue in TRACKED_ISSUES:
+        req = Request(f'{API_BASE}/repos/{REPO}/issues/{issue["number"]}', headers=headers)
+        with urlopen(req, timeout=30) as response:
+            data = json.loads(response.read().decode())
+        states[issue['number']] = {
+            'number': data['number'],
+            'title': data['title'],
+            'state': data['state'],
+            'html_url': data.get('html_url'),
+        }
+    return states
+
+
+def evidence_status(repo_root: Path, issue: dict) -> tuple[str, str]:
+    evidence = issue['evidence']
+    rel_path = evidence['path']
+    snippets = evidence['snippets']
+    content = (repo_root / rel_path).read_text(encoding='utf-8')
+    matches = [snippet for snippet in snippets if snippet in content]
+    if len(matches) == len(snippets):
+        proof = f"{rel_path} ({', '.join(f'`{snippet}`' for snippet in snippets)})"
+        return 'present', proof
+
+    missing = [snippet for snippet in snippets if snippet not in matches]
+    proof = f"missing in {rel_path}: {', '.join(f'`{snippet}`' for snippet in missing)}"
+    return 'missing', proof
+
+
+def render_markdown(rows: Iterable[dict]) -> str:
+    rows = list(rows)
+    open_count = sum(1 for row in rows if row['forge_state'] == 'open')
+    closed_count = sum(1 for row in rows if row['forge_state'] == 'closed')
+    present_count = sum(1 for row in rows if row['repo_evidence'] == 'present')
+    missing_count = sum(1 for row in rows if row['repo_evidence'] == 'missing')
+
+    lines = [
+        '# Paperclips Deep Study — Implementation Tracker',
+        '',
+        f'Grounded status snapshot for epic #{EPIC_NUMBER}.',
+        'This report tracks live forge issue state against visible repo evidence.',
+        'It does not claim the epic is complete; it shows what is present vs missing today.',
+        '',
+        f'- Forge issues: {open_count} open / {closed_count} closed',
+        f'- Repo evidence: {present_count} present / {missing_count} missing',
+        '',
+        '| Issue | Title | Forge state | Repo evidence | Proof |',
+        '| --- | --- | --- | --- | --- |',
+    ]
+
+    for row in rows:
+        lines.append(
+            f"| #{row['number']} | {row['title']} | {row['forge_state']} | {row['repo_evidence']} | {row['proof']} |"
+        )
+
+    lines.extend(
+        [
+            '',
+            '## Notes',
+            '',
+            '- `present` means the repository contains directly relevant code or docs markers for that study item.',
+            '- `missing` means the tracker could not find the expected markers yet; that child issue likely still needs a dedicated repo-side slice.',
+            '- Because #15 is an epic tracker, this artifact should advance the issue with `Refs #15`, not close it.',
+            '',
+        ]
+    )
+    return '\n'.join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--repo-root', default='.', help='Path to the-beacon checkout')
+    parser.add_argument('--issues-json', help='Optional local JSON file with issue records for offline testing')
+    parser.add_argument('--output', required=True, help='Where to write the markdown tracker')
+    args = parser.parse_args()
+
+    repo_root = Path(args.repo_root).resolve()
+    issue_states = load_issue_states(args.issues_json)
+
+    rows = []
+    for issue in TRACKED_ISSUES:
+        state = issue_states.get(issue['number'], {})
+        repo_evidence, proof = evidence_status(repo_root, issue)
+        rows.append(
+            {
+                'number': issue['number'],
+                'title': state.get('title', issue['title']),
+                'forge_state': state.get('state', 'unknown'),
+                'repo_evidence': repo_evidence,
+                'proof': proof,
+            }
+        )
+
+    output = Path(args.output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(render_markdown(rows), encoding='utf-8')
+    print(output)
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

tests/test_paperclips_tracker.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPT = ROOT / 'scripts' / 'paperclips_tracker.py'
+
+ISSUES = [
+    {'number': 2, 'title': '[P0] Paperclips-style Project Chain System', 'state': 'open'},
+    {'number': 3, 'title': '[P0] Creative Compute (Quantum Burst System)', 'state': 'closed'},
+    {'number': 4, 'title': '[P0] Compute Budget Supply/Demand Momentum', 'state': 'open'},
+    {'number': 5, 'title': '[P1] Strategy Engine Game Theory Tournaments', 'state': 'open'},
+    {'number': 6, 'title': '[P1] Community Swarm Alignment Simulation', 'state': 'open'},
+    {'number': 7, 'title': '[P1] Fibonacci Trust Milestone System', 'state': 'open'},
+    {'number': 8, 'title': '[P1] Investment Engine Research Grants', 'state': 'open'},
+    {'number': 9, 'title': '[P2] Emotional Arc Milestone Narrative System', 'state': 'closed'},
+    {'number': 10, 'title': '[P2] Number Formatting spellf equivalent', 'state': 'closed'},
+    {'number': 11, 'title': '[P2] Offline Progress Calculation', 'state': 'closed'},
+    {'number': 12, 'title': '[P2] Prestige New Game+ System', 'state': 'open'},
+    {'number': 13, 'title': '[P3] Deploy Beacon as Static Site', 'state': 'closed'},
+    {'number': 14, 'title': '[P3] Paperclips Architecture Comparison Document', 'state': 'open'},
+]
+
+
+def run_tracker(tmp_path: Path) -> str:
+    issues_path = tmp_path / 'issues.json'
+    output_path = tmp_path / 'tracker.md'
+    issues_path.write_text(json.dumps(ISSUES), encoding='utf-8')
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            str(SCRIPT),
+            '--repo-root',
+            str(ROOT),
+            '--issues-json',
+            str(issues_path),
+            '--output',
+            str(output_path),
+        ],
+        capture_output=True,
+        text=True,
+    )
+
+    assert result.returncode == 0, result.stderr or result.stdout
+    return output_path.read_text(encoding='utf-8')
+
+
+def test_tracker_renders_summary_counts(tmp_path: Path) -> None:
+    report = run_tracker(tmp_path)
+
+    assert '# Paperclips Deep Study — Implementation Tracker' in report
+    assert '- Forge issues: 8 open / 5 closed' in report
+    assert '- Repo evidence: 8 present / 5 missing' in report
+
+
+def test_tracker_renders_issue_rows_with_grounded_evidence(tmp_path: Path) -> None:
+    report = run_tracker(tmp_path)
+
+    assert '| #2 | [P0] Paperclips-style Project Chain System | open | present |' in report
+    assert '| #3 | [P0] Creative Compute (Quantum Burst System) | closed | present |' in report
+    assert '| #8 | [P1] Investment Engine Research Grants | open | missing |' in report
+    assert '| #14 | [P3] Paperclips Architecture Comparison Document | open | missing |' in report
+    assert 'js/data.js (`p_quantum_compute`, `Quantum-Inspired Compute`)' in report
+    assert 'README.md (`No build step required`, `static HTML/JS game`)' in report