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

ADR Revisions, LSP Integration Research, and Code Health Audit

• Session Summary
  • Date: 2025-12-24 (Late night session)
  • Focus Area: Skills+Molecules ADR refinement, Claude Code LSP integration research, codebase health audit
• Accomplishments
• Key Decisions
  • Decision 1: Use HMAC-based redaction instead of plain [REDACTED]
  • Decision 2: Nix store path as primary version identity
  • Decision 3: Park skills+molecules ADR work
  • Decision 4: File all code health findings as beads issues
• Problems & Solutions
• Technical Details
  • Code Changes
  • Commands Used
  • Architecture Notes
• Process and Workflow
  • What Worked Well
  • What Was Challenging
• Learning and Insights
  • Technical Insights
  • Process Insights
  • Architectural Insights
• Context for Future Work
  • Open Questions
  • Next Steps
  • Related Work
• Raw Notes
• Session Metrics

Session Summary

Date: 2025-12-24 (Late night session)

Focus Area: Skills+Molecules ADR refinement, Claude Code LSP integration research, codebase health audit

Accomplishments

• Revised ADR-002 (Skill Manifest Format) based on orch consensus feedback
• Revised ADR-003 (Skill Versioning Strategy) with Nix store paths, lockfiles, interface contracts
• Revised ADR-004 (Trace Security and Redaction) with HMAC redaction, entropy detection
• Updated orch skill to match CLI v0.1.0 (new model aliases, features)
• Researched Claude Code LSP integration via orch web search (sonar, flash-or, glm)
• Brainstormed LSP use cases via orch consensus (gpt, qwen, gemini, serial, temp 1.4)
• Created 9 beads issues for LSP integration ideas
• Conducted comprehensive code health audit of skills repo
• Filed 11 beads issues from code health findings
• 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

# 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

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)