docs: worklog for ADR revision, LSP research, code audit session

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/worklogs/2025-12-24-adr-revision-lsp-research-code-audit.org

@@ -0,0 +1,166 @@
+#+TITLE: ADR Revisions, LSP Integration Research, and Code Health Audit
+#+DATE: 2025-12-24
+#+KEYWORDS: ADR, orch-consensus, LSP, code-audit, beads, skills-molecules, refactoring
+#+COMMITS: 6
+#+COMPRESSION_STATUS: uncompressed
+
+* Session Summary
+** Date: 2025-12-24 (Late night session)
+** Focus Area: Skills+Molecules ADR refinement, Claude Code LSP integration research, codebase health audit
+
+* Accomplishments
+- [X] Revised ADR-002 (Skill Manifest Format) based on orch consensus feedback
+- [X] Revised ADR-003 (Skill Versioning Strategy) with Nix store paths, lockfiles, interface contracts
+- [X] Revised ADR-004 (Trace Security and Redaction) with HMAC redaction, entropy detection
+- [X] Updated orch skill to match CLI v0.1.0 (new model aliases, features)
+- [X] Researched Claude Code LSP integration via orch web search (sonar, flash-or, glm)
+- [X] Brainstormed LSP use cases via orch consensus (gpt, qwen, gemini, serial, temp 1.4)
+- [X] Created 9 beads issues for LSP integration ideas
+- [X] Conducted comprehensive code health audit of skills repo
+- [X] Filed 11 beads issues from code health findings
+- [X] Parked skills-hin (ADR finalization) pending Steve Yegge's orchestration work
+- [ ] Remote git server unavailable - commits pending push
+
+* Key Decisions
+** Decision 1: Use HMAC-based redaction instead of plain [REDACTED]
+- Context: Traces need to redact sensitive data but allow correlation
+- Options considered:
+  1. Plain [REDACTED] - simple but loses all information
+  2. HMAC hash prefix - enables correlation without revealing values
+- Rationale: HMAC allows detecting if same secret used across executions
+- Impact: ADR-004 now specifies [REDACTED:hmac:abc123] format
+
+** Decision 2: Nix store path as primary version identity
+- Context: Skills deployed via Nix need reproducible version tracking
+- Options considered:
+  1. Git SHA only - may not exist for local changes
+  2. Content hash only - portable but requires computation
+  3. Nix store path - immutable, content-addressed by Nix itself
+- Rationale: Nix already solves content addressing; use it when available
+- Impact: ADR-003 now uses nix_store_path as primary identity for Nix-deployed skills
+
+** Decision 3: Park skills+molecules ADR work
+- Context: Steve Yegge working on new AI orchestration approach
+- Rationale: Wait to see if his approach informs our design before finalizing
+- Impact: skills-hin moved to open status with note about deferral
+
+** Decision 4: File all code health findings as beads issues
+- Context: Code audit revealed significant technical debt
+- Rationale: Track systematically rather than try to fix immediately
+- Impact: 11 new issues filed covering refactoring, testing, dead code
+
+* Problems & Solutions
+| Problem | Solution | Learning |
+|---------+----------+----------|
+| Orch skill out of sync with CLI | Read models_registry.py and README, rewrote SKILL.md | Skills deployed via Nix need source in skills/*/SKILL.md |
+| Skill file is in Nix store (read-only) | Found source at /home/dan/proj/skills/skills/orch/SKILL.md | home-manager deploys from skills repo, not direct edit |
+| Remote git server unavailable | Local commits preserved, bd sync exports to JSONL | Beads resilient to network issues |
+| Qwen model errors in orch consensus | Used GPT and Gemini instead, still got good coverage | Have fallback models ready |
+
+* Technical Details
+
+** Code Changes
+- Total files modified: 8
+- Key files changed:
+  - ~docs/adr/002-skill-manifest-format.md~ - Added JSON Schema, path bases, timeout
+  - ~docs/adr/003-skill-versioning-strategy.md~ - Nix store paths, lockfiles, .skillignore
+  - ~docs/adr/004-trace-security-redaction.md~ - HMAC redaction, entropy detection, trace modes
+  - ~skills/orch/SKILL.md~ - Updated model aliases, new features documented
+- New files created: None (all edits to existing)
+- Lines: +1591 / -38
+
+** Commands Used
+#+begin_src bash
+# Orch consensus with web search
+cd ~/proj/orch && uv run orch consensus "Claude Code LSP integration..." sonar flash-or glm --mode open
+
+# Orch brainstorm with high temperature
+uv run orch consensus "..." gpt qwen gemini --serial --temperature 1.4 --mode brainstorm
+
+# Check orch model registry
+uv run orch models
+
+# Beads batch operations
+bd close skills-oes skills-8y6 skills-be3 --reason="ADRs revised"
+bd dep add skills-le9 skills-gga  # Add dependency
+#+end_src
+
+** Architecture Notes
+- Skills deployed via Nix/home-manager from skills repo source
+- Dotfiles flake imports skills as input, runs deploy.sh
+- LSP integration requires ENABLE_LSP_TOOL=1 env var
+- LSP skills blocked by skills-gga (configure LSP first)
+
+* Process and Workflow
+
+** What Worked Well
+- Orch consensus for ADR review - got actionable feedback from multiple models
+- Serial mode with high temp (1.4) produced creative brainstorming
+- Human-in-the-loop ADR revision - presented changes, got approval, wrote
+- Parallel beads issue creation - efficient batch filing
+- Code health audit via Explore agent - comprehensive without manual grep
+
+** What Was Challenging
+- Remote git server down all session - couldn't push
+- Plan mode accidentally activated during skill update
+- SQLite database temporarily closed during batch issue creation (2 retries)
+- Finding skill source location (Nix store symlinks)
+
+* Learning and Insights
+
+** Technical Insights
+- Claude Code LSP uses standard language servers (gopls, pyright, rust-analyzer)
+- LSP provides: go-to-definition, find-references, hover, diagnostics
+- Can use LSP as "ground truth" to validate model suggestions before applying
+- HMAC redaction allows correlation without revealing secrets
+
+** Process Insights
+- Orch consensus with 3+ models provides good coverage of perspectives
+- Serial mode with debate/refine strategies could improve synthesis
+- --synthesize flag useful for aggregating multi-model responses
+- Temperature 1.4 too high for some models (qwen clamped to 1.0)
+
+** Architectural Insights
+- Skills repo is source of truth, dotfiles deploys via Nix
+- LSP could be foundation for many skill improvements (semantic-grep, rename, etc.)
+- Code health issues reveal .specify scripts need most attention
+- Test coverage is zero - significant gap for critical bash scripts
+
+* Context for Future Work
+
+** Open Questions
+- What is Steve Yegge building for AI orchestration?
+- Should LSP be always-on or on-demand in Claude Code?
+- How to handle skills that span multiple molecule steps?
+- Minimum executions before suggesting elevation to skill?
+
+** Next Steps
+- Push commits when remote available
+- Configure Claude Code LSP (skills-gga) to unblock 6 downstream issues
+- Consider tackling update-agent-context.sh refactoring (skills-p2o, skills-vjm)
+- Research Steve Yegge's work before finalizing ADRs
+
+** Related Work
+- ADRs: docs/adr/001-004
+- Previous worklog: 2025-12-17-wayland-desktop-automation-seeing-problem.org
+- Orch repo: ~/proj/orch (recently updated with centralized model registry)
+- Beads molecule commands: bd mol, bd wisp, bd pour (beads 0.35+)
+
+* Raw Notes
+- Orch model aliases changed: gpt now gpt-5.2, opus now claude-opus-4.5
+- New orch features: --synthesize, stdin piping, orch models, orch sessions
+- LSP brainstorm produced 32 ideas across 3 models
+- Best ideas: semantic-grep, Nix-LSP autopoiesis (rejected), bead-driven development
+- Code audit found 772-line update-agent-context.sh as worst offender
+- 12 nearly-identical if-blocks should be array+loop
+
+Session ran late night into early morning (past 2am).
+
+* Session Metrics
+- Commits made: 6 (3 today by metrics, but 6 total ahead of origin)
+- Files touched: 8
+- Lines added/removed: +1591/-38
+- Tests added: 0
+- Tests passing: N/A (no test suite exists)
+- Beads issues created: ~20 (LSP + code health)
+- Beads issues closed: 4 (ADR design issues)