# Project State Maintenance — Unspooled

## File Location

The authoritative project state document is `~/Unspooled/PROJECT_STATE.md` (uppercase). It is version-controlled in the repo. **Do NOT create `/home/rurouni/project_state.md`** or any other lowercase duplicate at the home directory.

Every new session reads this first. Update it when development scope changes.

## Full Audit Workflow

When the user says "update project state" or "do an audit", do a comprehensive check — not just a commit hash bump:

### 1. Git State
- Branch: `git branch --show-current`
- Recent commits: `git log --oneline -10`
- Ahead/behind origin/master: `git rev-list --left-right --count origin/master...HEAD`
- Working tree: `git status --short`
- Unmerged branches: `git branch -a` (check for orphaned feature branches)
- Stash: `git stash list`

### 2. Compile
```bash
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
./gradlew :app:compileDebugKotlin --console=plain
```

### 3. Tests
```bash
./gradlew :app:testDebugUnitTest --console=plain
```
Verify count matches what's in PROJECT_STATE.md (currently 171 tests).

### 4. Lint
```bash
./gradlew :app:lintDebug --console=plain 2>&1 | tail -10
```
Document error/warning breakdown by category:
```
grep 'Error:' lint-results.txt | awk -F'[' '{print $2}' | awk -F']' '{print $1}' | sort | uniq -c | sort -rn
grep 'Warning:' lint-results.txt | same pattern
```

### 5. File Counts
```bash
find app/src -name '*.kt' -type f | wc -l
find app/src/main/java/com/unspooled/app -name '*.kt' -type f \
  | awk -F'/com/unspooled/app/' '{print $2}' \
  | awk -F'/' '{print $1}' | sort | uniq -c | sort -rn
```

### 6. APK
```bash
ls -lh app/build/outputs/apk/debug/app-debug.apk
```

### 7. Cleanup stale artifacts
- Delete any stale `project_state.md` (lowercase) at wrong paths
- Delete fully-actioned audit `.md` documents (content should be merged into PROJECT_STATE.md)
- Delete old `.hermes/plans/*.md` for completed work
- Drop stale stashes from git

### 8. Fix quick wins during audit
- Fix any SuspiciousIndentation lint errors found (they're usually real)
- Leave the structural changes (RestrictedApi, UnusedResources) documented as known debt

### 9. Update PROJECT_STATE.md
Structure to maintain:
- Header: repo URL, branch, last commit (full SHA + message), app ID, APK size
- Quick Start: build/test commands
- Audit Snapshot table: compile | tests | APK | lint errors | lint warnings | git divergence
- What This App Does
- File Counts & Structure (per-package breakdown)
- Screens table (35 routes)
- Architecture
- Design System (V2)
- Focus Architecture (V5)
- Player Architecture
- Debrid Integration
- Scraper (nexstream-scraper)
- Security
- Dependencies table
- Git Conventions
- Lint Debt section with error/warning breakdown
- Completed Phases (ongoing log)
- Key Pitfalls (19+ items)
- Session Handoff Notes (11 items)
- Built-In Addons
- Baseline Profile
- Known Issues

### 10. Verify
```bash
./gradlew :app:compileDebugKotlin :app:testDebugUnitTest --console=plain
git diff --stat  # review what changed
```