#+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)