🐛 Fix ES module import issues and add comprehensive style guide

[AdaInTheLab]

Summary

Fix critical ES module import errors that prevented the CLI from running, and establish comprehensive style guides to prevent future issues.

Changes

Bug Fixes

1. capabilities.ts: Add missing .js extension

   // Before
   import { CLI_SCHEMA_VERSION } from "./schema";
   
   // After
   import { CLI_SCHEMA_VERSION } from "./schema.js";

2. version.ts: Fix package.json path for compiled code

   // Before (works in dev, breaks in production)
   const pkg = require("../../package.json");
   
   // After (works from compiled location)
   const pkg = require("../../../package.json");

Style Guide

Added two comprehensive documentation files:

1. STYLE_GUIDE.md (Full guide)

   • ES modules import rules (CRITICAL)
   • File structure & naming conventions
   • Code patterns & templates
   • Commit message format (lore-coded)
   • Testing & building process
   • Common gotchas with solutions
   • Contract guarantees
   • Development workflow

2. QUICK_REFERENCE.md (One-page cheat sheet)

   • Quick commands
   • Pattern templates
   • Debugging table
   • Emergency fixes
   • Print-and-keep format

Why This Matters

Node.js ES Modules require explicit .js extensions for relative imports. TypeScript doesn't add them automatically, so they must be written in source files even though the actual files are .ts.

The style guide prevents this and other common issues by documenting:

• The OPS [CJO] Fix Carmel workflow validation #1 gotcha (missing .js extensions)
• How to set up VS Code to auto-add extensions
• Patterns for common tasks
• Debugging steps for common errors

Testing

• CLI builds successfully: npm run build
• Global install works: npm install -g .
• Commands functional:
  • hpl version - Shows version
  • hpl capabilities - Lists capabilities
  • hpl health - Checks API health
  • hpl version --json - JSON output works
• No import errors
• No module not found errors

Breaking Changes

None - all changes are bug fixes and documentation.

Impact

Before: CLI unusable due to ES module errors
After: CLI fully functional + guides to prevent future issues

Time saved: ~2-4 hours per new contributor who would have hit these issues

Related

• Fixes issues discovered during Liminal Bridge implementation
• Part of broader effort to improve developer experience

Checklist

• Code follows style guide (now documented!)
• All tests passing
• Documentation comprehensive
• Commit messages follow lore-coded format
• No breaking changes

---

These guides will help future contributors (and AI assistants) avoid the same pitfalls!

Co-authored-by: Sage sage@thehumanpatternlab.com

[github-actions]

😼🔥 Carmel Chaos Stamp™

I sense weakness in these tests.

[github-actions]

😼✨ Carmel Approval Stamp™

Adequate work, human.