@codeyam/codeyam-cli 0.1.0-staging.2a88920 → 0.1.0-staging.483fdc2

package/codeyam-cli/src/webserver/build/server/index.js

@@ -1 +1 @@
-import{Y as H,Z as I,M as J,N as K,W as L,O as _,R as $,T as rr,V as tr,U as or,X as ir,Q as pr}from"./assets/server-build-dYC34MHw.js";import"react/jsx-runtime";import"node:stream";import"@react-router/node";import"react-router";import"isbot";import"react-dom/server";import"react";import"lucide-react";import"fetch-retry";import"better-sqlite3";import"pg";import"fs";import"path";import"kysely";import"kysely/helpers/sqlite";import"kysely/helpers/postgres";import"typescript";import"fs/promises";import"os";import"prompts";import"chalk";import"crypto";import"child_process";import"url";import"util";import"dotenv";import"events";import"uuid";import"openai";import"p-queue";import"p-retry";import"@aws-sdk/client-dynamodb";import"lru-cache";import"pluralize";import"piscina";import"json5";import"@aws-sdk/util-dynamodb";import"v8";import"react-syntax-highlighter";import"react-syntax-highlighter/dist/cjs/styles/prism/index.js";import"node:crypto";import"minimatch";import"react-markdown";import"remark-gfm";import"react-diff-viewer-continued";export{H as allowedActionOrigins,I as assets,J as assetsBuildDirectory,K as basename,L as entry,_ as future,$ as isSpaMode,rr as prerender,tr as publicPath,or as routeDiscovery,ir as routes,pr as ssr};
+import{Y as H,Z as I,M as J,N as K,W as L,O as _,R as $,T as rr,V as tr,U as or,X as ir,Q as pr}from"./assets/server-build-BQ-1XyEa.js";import"react/jsx-runtime";import"node:stream";import"@react-router/node";import"react-router";import"isbot";import"react-dom/server";import"react";import"lucide-react";import"fetch-retry";import"better-sqlite3";import"pg";import"fs";import"path";import"kysely";import"kysely/helpers/sqlite";import"kysely/helpers/postgres";import"typescript";import"fs/promises";import"os";import"prompts";import"chalk";import"crypto";import"child_process";import"url";import"util";import"dotenv";import"events";import"uuid";import"openai";import"p-queue";import"p-retry";import"@aws-sdk/client-dynamodb";import"lru-cache";import"pluralize";import"piscina";import"json5";import"@aws-sdk/util-dynamodb";import"v8";import"react-syntax-highlighter";import"react-syntax-highlighter/dist/cjs/styles/prism/index.js";import"node:crypto";import"minimatch";import"react-markdown";import"remark-gfm";import"react-diff-viewer-continued";export{H as allowedActionOrigins,I as assets,J as assetsBuildDirectory,K as basename,L as entry,_ as future,$ as isSpaMode,rr as prerender,tr as publicPath,or as routeDiscovery,ir as routes,pr as ssr};

package/codeyam-cli/src/webserver/build-info.json

@@ -1,7 +1,7 @@
 {
-  "buildTimestamp": "2026-02-03T16:02:39.433Z",
-  "buildTime": 1770134559433,
-  "buildNumber": 579,
-  "semanticVersion": "0.1.579",
-  "version": "0.1.579 (2026-02-03T16:02)"
+  "buildTimestamp": "2026-02-04T17:33:55.043Z",
+  "buildTime": 1770226435043,
+  "buildNumber": 583,
+  "semanticVersion": "0.1.583",
+  "version": "0.1.583 (2026-02-04T17:33)"
 }

package/codeyam-cli/templates/codeyam:memory.md

@@ -3,13 +3,29 @@ name: codeyam:memory
 autoApprove: true
 description: |
   Generate and maintain Claude Rules for your codebase based on thorough analysis.
-  Use when: User wants to set up memory, claude rules, document confusing areas, 
+  Use when: User wants to set up memory, claude rules, document confusing areas,
   or ensure Claude has proper context for working in the codebase.
 ---
 
 # CodeYam Memory Assistant
 
-This skill helps you generate and maintain Claude Rules (`.claude/rules/`) that provide context-specific guidance. The goal is robust coverage of anything confusing while avoiding documentation of things Claude can intuit.
+This skill helps you generate and maintain Claude Rules (`.claude/rules/`) that provide context-specific guidance. The goal is to **document genuinely confusing aspects** of the codebase—not things Claude can figure out by reading code.
+
+## Core Principle: Document Confusion, Not Information
+
+**Good rules** explain things that are NOT obvious from reading the code:
+
+- Historical context (why code evolved this way)
+- Hidden relationships (files that must change together)
+- Gotchas that caused bugs
+- Non-obvious conventions
+
+**Bad rules** document things Claude can easily ascertain:
+
+- What functions do (Claude can read the code)
+- Type definitions (Claude can see them)
+- Directory structure (Claude can explore it)
+- Basic patterns (Claude knows common patterns)
 
 ## When to Use This Skill
 
@@ -66,176 +82,170 @@ Ensure `.codeyam/bin/memory-hook.sh` exists and is executable (`chmod +x`).
 
 ---
 
-## Phase 2: Deep Codebase Analysis
+## Phase 2: Confusion Archaeology
 
-Perform thorough analysis to identify areas that may be confusing. The goal is to find everything that might trip up someone (or Claude) working in this codebase.
+The goal is to find areas where developers have **struggled**—not just areas that are complex. High churn alone doesn't mean confusion; we're looking for patterns that indicate something is genuinely non-obvious.
 
-### 2A. Analyze Git Commit Messages for Problem Signals
+### 2A. Find Confusion Signals in Commit History
 
-Look for commits indicating gotchas, workarounds, or complexity:
+**Files with rapid successive changes** (same file, multiple commits in short windows = iteration/confusion):
 
 ```bash
-# Find commits with problem-indicating keywords
-git log --oneline --since="6 months ago" --grep="fix" --grep="bug" --grep="workaround" --grep="hack" --grep="revert" --grep="oops" --grep="forgot" --grep="actually" --all-match | head -30
+# Files changed 3+ times in last month (rapid iteration signal)
+git log --since="1 month ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | awk '$1 >= 3 {print}' | head -20
+```
 
-# Find commits with long messages (indicate complex changes)
-git log --since="6 months ago" --format="%h %s" | awk 'length($0) > 80' | head -20
+**Reverts** (definite confusion signals—someone made a change that didn't work):
 
-# Find reverted commits
-git log --oneline --since="6 months ago" --grep="revert" -i | head -10
+```bash
+git log --since="6 months ago" --oneline --grep="[Rr]evert" | head -10
 ```
 
-For interesting commits, examine the full message and changes:
+**Correction language** (commits that fix misunderstandings):
 
 ```bash
-git show <commit-hash> --stat
-git log -1 --format="%B" <commit-hash>
+git log --since="6 months ago" --oneline | grep -iE "(oops|forgot|actually|wrong|typo|missing|should have|meant to)" | head -15
 ```
 
-### 2B. Identify Files with High Churn or Complexity Signals
+**Files with multiple fix commits** (confusion hotspots):
 
 ```bash
-# Files changed most frequently (last 6 months)
-git log --since="6 months ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -30
+git log --since="3 months ago" --oneline --grep="fix" -i --name-only --pretty=format: | sort | uniq -c | sort -rn | awk '$1 >= 2 {print}' | head -15
+```
 
-# Files with many different authors (tribal knowledge risk)
-git shortlog -sn --since="6 months ago" -- . | head -20
+**Long commit messages** (someone felt the need to explain—complexity that needs documentation):
 
-# Files frequently modified together (hidden dependencies)
-git log --since="6 months ago" --name-only --pretty=format: | awk '/^$/{if(NR>1)print "---"}; /./{print}' | head -100
+```bash
+git log --since="6 months ago" --format="%h %s" | awk 'length($0) > 100' | head -15
 ```
 
-Look for patterns where the same 2-3 files appear together repeatedly.
+### 2B. Dig Into High-Confusion Files
 
-### 2C. Scan for Developer Notes in Code
+For each file that shows confusion signals, examine its evolution:
 
 ```bash
-# Find TODO, FIXME, HACK, XXX, NOTE comments
-grep -rn "TODO\|FIXME\|HACK\|XXX\|NOTE:" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" --include="*.rb" --include="*.go" --include="*.java" --include="*.rs" . 2>/dev/null | head -50
+# View the story of changes to understand what kept going wrong
+git log --since="6 months ago" --oneline -- path/to/confusing-file.ts
 
-# Find "workaround" or "hack" mentions in comments
-grep -rni "workaround\|hack\|temporary\|legacy" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" . 2>/dev/null | head -30
+# Read the full commit messages for context
+git log --since="6 months ago" --format="%h %s%n%b" -- path/to/confusing-file.ts | head -100
 ```
 
-### 2D. Analyze Project Structure
+**As you analyze, ask:**
 
-```bash
-# Get directory structure (2 levels deep)
-find . -type d -maxdepth 3 | grep -v node_modules | grep -v .git | grep -v dist | grep -v build | head -50
+- What was the initial implementation?
+- What kept breaking or needed fixing?
+- What was non-obvious about the fix?
+- What knowledge would have prevented the issue?
+
+### 2C. Find Hidden Dependencies
 
-# Find config files
-find . -name "*.config.*" -o -name "*.rc" -o -name ".env*" -o -name "tsconfig*" -o -name "package.json" 2>/dev/null | grep -v node_modules | head -30
+**Files that always change together** (may have non-obvious relationships):
 
-# Find test directories
-find . -type d -name "*test*" -o -type d -name "*spec*" -o -type d -name "__tests__" 2>/dev/null | grep -v node_modules | head -20
+```bash
+# Look for file pairs that frequently appear in the same commits
+git log --since="3 months ago" --name-only --pretty=format: | awk 'NF' | sort | uniq -c | sort -rn | head -30
 ```
 
-### 2E. Check for Environment and Configuration Complexity
+When you see the same files appearing together repeatedly, investigate why they're coupled.
 
-```bash
-# Find environment variable references
-grep -rn "process.env\|os.environ\|ENV\[" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" . 2>/dev/null | head -30
+### 2D. Scan for Developer Notes
+
+**TODO/FIXME/HACK comments** often mark confusion points:
 
-# Find multiple config files that might conflict or confuse
-ls -la *.config.* .*.rc tsconfig*.json 2>/dev/null
+```bash
+grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" . 2>/dev/null | head -30
 ```
 
-### 2F. Review Existing Documentation
+Focus on comments that explain **why** something is the way it is, not just **what** needs to be done.
+
+### 2E. Review Existing Documentation
 
-Read these files if they exist:
+Read these files if they exist to understand what's already documented:
 
 - `README.md`
 - `CLAUDE.md`
 - `CONTRIBUTING.md`
 - `docs/` directory
-- Any `*.md` files in the root
 
-Note what's already documented and what gaps exist.
-
-### 2G. Examine Import/Dependency Patterns
-
-```bash
-# Find files with many imports (high coupling)
-for f in $(find . -name "*.ts" -o -name "*.tsx" -o -name "*.js" 2>/dev/null | grep -v node_modules | head -100); do
-  count=$(grep -c "^import\|^from\|require(" "$f" 2>/dev/null || echo 0)
-  if [ "$count" -gt 15 ]; then
-    echo "$count $f"
-  fi
-done | sort -rn | head -20
-
-# Find commonly imported local modules (core utilities)
-grep -rh "from '\.\|from \"\.\|require('\.\|require(\"\." --include="*.ts" --include="*.tsx" --include="*.js" . 2>/dev/null | sort | uniq -c | sort -rn | head -20
-```
+Note gaps between what's documented and the confusion signals you found.
 
 ---
 
-## Phase 3: Cluster and Prioritize Findings
+## Phase 3: Distinguish Important from Confusing
 
-After gathering signals, organize them by area/module:
+Not all high-churn areas need documentation. Filter your findings:
 
-1. **Group findings by directory** - Which parts of the codebase have the most signals?
-2. **Identify themes**:
-   - Architecture patterns (how things connect)
-   - Testing complexity (special setup needed)
-   - Configuration/environment gotchas
-   - Historical workarounds still in place
-   - Non-obvious conventions
+### Skip These (High Churn but NOT Confusing)
 
-3. **Score areas** - More signals = higher priority for documentation
+- Lock files (`pnpm-lock.yaml`, `package-lock.json`)
+- Build outputs (`dist/`, `build/`)
+- Generated files (`.build-info.json`, etc.)
+- Files with mechanical changes (version bumps, auto-formatting)
 
-Create a mental map of:
+### Document These (High Churn AND Confusing)
 
-- Which directories/modules are most complex?
-- What relationships exist between different parts?
-- Where are the gotchas hiding?
+- Files with multiple fix commits in short windows
+- Files with reverts (someone's approach didn't work)
+- Files where commit messages explain complex reasoning
+- Files where the same area keeps breaking
+- Files that must change together but aren't obviously related
 
----
+### Confusion Scoring
 
-## Phase 4: Ask Specific Questions
+Prioritize areas with stronger confusion signals:
 
-Based on your analysis, ask the user specific questions about the actual findings. Reference the concrete evidence you found (file names, commit messages, code patterns) and ask about the substance.
+| Signal                    | Weight | Example                           |
+| ------------------------- | ------ | --------------------------------- |
+| Reverts                   | 5      | "Revert 'Track useState sources'" |
+| Correction language       | 5      | "Oops, forgot to import..."       |
+| Follow-up fix within days | 5      | Fix commit 2 days after change    |
+| "Workaround" or "hack"    | 3      | "Workaround for webpack issue"    |
+| Long commit message       | 3      | >100 chars explaining complexity  |
+| Multiple fix commits      | 2      | 3+ fixes to same file             |
+| Numbered fix series       | 1      | "Analysis Fixes 4", "Fixes 5"     |
 
-Always include "I'm not sure - please investigate" as an option so users can delegate investigation to you.
+Focus your documentation efforts on areas with the highest confusion scores.
 
-### Question Format
+---
 
-Ask about the **specific finding**, not the file generally:
+## Phase 4: Ask Evidence-Based Questions
 
-**For high-churn files with concerning commits:**
+Questions must reference **specific confusion evidence** you found. Don't ask generic questions about files; ask about the specific commits, patterns, or problems you discovered.
 
-> "ScopeDataStructure.ts has commits mentioning 'exponential blowup' and 'execution flows'. What causes this blowup? When does it happen?"
->
-> Options: [Explain the cause] [I'm not sure - please investigate]
+Always include "I'm not sure - please investigate" as an option so users can delegate investigation to you.
+
+### Question Examples
 
-**For files frequently modified together:**
+**For rapid successive changes:**
 
-> "`src/api/auth.ts` and `src/middleware/session.ts` are modified together in 12 commits. Why do these need to change together?"
+> "I found 5 commits to `ScopeDataStructure.ts` in 3 weeks, including 'Fix exponential blowup' and 'scope data structure optimization'. What kept causing issues here? What would someone need to know to avoid similar problems?"
 >
-> Options: [Explain the relationship] [I'm not sure - please investigate]
+> Options: [Explain the pattern] [I'm not sure - please investigate]
 
-**For commits with workaround language:**
+**For reverts:**
 
-> "Commit `abc123` says 'workaround for webpack issue'. What's the underlying issue and what's the workaround?"
+> "Commit `a9fbd6385` reverted 'Track useState initialization sources'. Why didn't that approach work? What should be done instead?"
 >
-> Options: [Explain] [I'm not sure - please investigate]
+> Options: [Explain what went wrong] [I'm not sure - please investigate]
 
-**For multiple config files:**
+**For correction commits:**
 
-> "There are 3 tsconfig files. When is each one used?"
+> "Commit `31e4a3842` says 'Oops, lost an import'. What import was lost and why is it easy to miss?"
 >
-> Options: [Explain usage] [I'm not sure - please investigate]
+> Options: [Explain the gotcha] [I'm not sure - please investigate]
 
-**For TODO/FIXME comments:**
+**For files that change together:**
 
-> "There's a FIXME in `src/parser.ts:142` about 'handle nested callbacks'. What's the issue with nested callbacks here?"
+> "I noticed `auth.ts` and `session.ts` are modified together in 8 commits. Is there an invariant that must be maintained between them? What would break if someone changed one without the other?"
 >
-> Options: [Explain] [I'm not sure - please investigate]
+> Options: [Explain the relationship] [I'm not sure - please investigate]
 
-**For test organization:**
+**For long explanatory commits:**
 
-> "Tests are split between `__tests__/` folders and colocated `*.test.ts` files. When should each approach be used?"
+> "Commit `abc123` has a detailed message about 'why we need to track execution flows separately'. What's the key insight here that should be documented?"
 >
-> Options: [Explain convention] [I'm not sure - please investigate]
+> Options: [Summarize the insight] [I'm not sure - please investigate]
 
 ### Process
 
@@ -249,11 +259,59 @@ Ask about the **specific finding**, not the file generally:
 
 ---
 
-## Phase 5: Generate Rules
+## Phase 5: Generate and Validate Rules
+
+For each area where you have enough information, create a rule file—but **validate it first**.
+
+### 5A. Rule Validation (Before Writing)
+
+Before generating each rule, verify it passes these tests:
+
+**1. Evidence check**: Does the rule reference actual confusion evidence from commit history?
+
+- If no evidence of confusion, reconsider whether the rule is needed
+
+**2. Code-derivable check**: Read the files the rule will cover. Could the rule's content be determined by reading those files alone?
+
+- If YES → rule probably not needed (Claude can read the code)
+- If NO (historical context, edge cases, non-obvious behavior) → rule is valuable
+
+**3. Prevention check**: Would this rule have prevented one of the confusion commits you found?
+
+- If YES → definitely document it
+- If NO → reconsider its value
+
+### Rule Quality Examples
+
+**✅ Good rule** (passes all tests):
+
+```markdown
+## Path Prefix Matching Must Check Boundaries
+
+When checking if one schema path is a prefix of another using `startsWith()`,
+you must verify the match is at a path boundary. Otherwise sibling properties
+with similar names incorrectly match.
+
+This caused a bug where `entity` matched `entityCode` (siblings, not parent-child).
+```
 
-For each area where you have enough information, create a rule file.
+- Evidence: Learned from actual bug (commit history evidence)
+- Not code-derivable: Code doesn't explain why boundary checking matters
+- Prevention: Would prevent future prefix-matching bugs
 
-### Rule File Guidelines:
+**❌ Bad rule** (fails tests):
+
+```markdown
+## Running Tests
+
+Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
+```
+
+- No confusion evidence (no commits showing people struggled with this)
+- Code-derivable: Anyone can see `jest.config.ts` exists
+- Doesn't prevent any confusion
+
+### 5B. Rule File Guidelines
 
 1. **Location mirrors code structure**
    - Rule for `src/api/` → `.claude/rules/src/api/architecture.md`
@@ -263,16 +321,15 @@ For each area where you have enough information, create a rule file.
    - Good: `paths: ['src/api/**/*.ts']`
    - Bad: `paths: ['**/*.ts']` (too broad, wastes context)
 
-3. **Content should be actionable**
-   - Focus on "how to" and "what to know"
-   - Avoid warnings unless truly critical
+3. **Content should explain "why" not just "what"**
+   - Focus on the reasoning, history, or gotcha
    - Be concise - every word costs context
 
 4. **Timestamp must be current**
    - Use ISO 8601 format: `2026-01-27T15:30:00Z`
    - This enables the pre-commit hook enforcement
 
-### Rule Template:
+### Rule Template
 
 ```markdown
 ---
@@ -284,11 +341,15 @@ timestamp: [CURRENT_ISO_TIMESTAMP]
 
 ## [Clear, Descriptive Title]
 
-[Concise explanation of what this covers]
+[What's the gotcha/insight/non-obvious thing?]
 
-### [Section as appropriate]
+### Why This Matters
 
-[Specific, actionable content]
+[What would go wrong if someone didn't know this?]
+
+### The Solution/Pattern
+
+[What should someone do differently?]
 ```
 
 ---
@@ -298,6 +359,7 @@ timestamp: [CURRENT_ISO_TIMESTAMP]
 After generating rules based on your analysis and user answers:
 
 1. **Present a summary** of all rules created
+
 2. **Ask the user:**
 
    > "I've created rules covering [list areas]. Are there any other areas of the codebase that you know are confusing or have tribal knowledge that I might have missed?"

package/codeyam-cli/templates/codeyam:new-rule.md

@@ -8,6 +8,45 @@ description: |
 
 # Create New Claude Rule
 
-Read `.codeyam/rules/instructions.md` for guidance on how to create and structure a new rule.
+## Before Creating: The Confusion Test
+
+Only create rules that document genuinely confusing aspects—not things Claude can figure out by reading code.
+
+**Ask yourself:**
+
+1. **Could Claude figure this out by reading the code?**
+   - If YES → don't create the rule
+   - If NO → proceed
+
+2. **Does this explain "why" not just "what"?**
+   - Good: Historical context, gotchas, non-obvious behavior
+   - Bad: What functions do, how files are structured
+
+3. **Would this have prevented a past mistake?**
+   - If you can point to a bug or confusion this would have prevented → create it
+   - If it's just "nice to know" → skip it
+
+## Creating the Rule
+
+Read `.codeyam/rules/instructions.md` for detailed guidance on structure and formatting.
 
 If the instructions file doesn't exist, copy it from `codeyam-cli/templates/rules-instructions.md`.
+
+### Quick Template
+
+```markdown
+---
+paths:
+  - 'specific/path/**/*.ts'
+category: architecture | testing | faq
+timestamp: [CURRENT_ISO_TIMESTAMP]
+---
+
+## [Clear, Descriptive Title]
+
+[What's the gotcha/insight/non-obvious thing?]
+
+### Why This Matters
+
+[What would go wrong if someone didn't know this?]
+```

package/codeyam-cli/templates/rule-reflection-hook.py

@@ -140,6 +140,7 @@ Guidelines:
     - Locations of tests
     - Commands that can be run that are relevant to the task at hand
     - Architectural design, where to look for, fix, or add certain things
+- Pay particular attention to times when the user must interrupt or correct Claude.
 - Do not document bugs being fixed as they will likely be resolved.
 - Issues that are abandoned as known issues can be noted.
 - Keep rules concise (<50 lines), use bullets/tables where appropriate.

package/codeyam-cli/templates/rules-instructions.md

@@ -17,6 +17,39 @@ Create a new rule when:
 - The user explains something that isn't clear from the code
 - An existing rule is covering multiple unrelated topics (split it)
 
+## Before Creating: The Confusion Test
+
+Before writing a rule, verify it passes these tests:
+
+**1. Could Claude figure this out by reading the code?**
+
+- If YES → don't create the rule (it documents the obvious)
+- If NO → the rule is valuable
+
+**2. Does this explain "why" not just "what"?**
+
+- Good: Explains historical context, gotchas, or non-obvious behavior
+- Bad: Describes what functions do or how files are structured
+
+**3. Would this have prevented a past mistake?**
+
+- If you can point to a commit, bug, or confusion this would have prevented → create it
+- If it's just "nice to know" information → skip it
+
+### Examples
+
+**✅ Worth documenting:**
+
+- "Path prefix matching must check boundaries" (learned from a bug)
+- "These files must change together because of X invariant" (hidden dependency)
+- "This pattern exists because the obvious approach causes Y problem" (non-obvious design)
+
+**❌ Not worth documenting:**
+
+- "Use `pnpm jest` to run tests" (obvious from package.json)
+- "The auth module handles authentication" (obvious from reading code)
+- "This function takes X and returns Y" (Claude can read the signature)
+
 ## Path Specificity
 
 The `paths` field controls when the rule is shown. Match the scope of your content:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam/codeyam-cli",
-  "version": "0.1.0-staging.2a88920",
+  "version": "0.1.0-staging.483fdc2",
   "description": "Local development CLI for CodeYam analysis",
   "type": "module",
   "bin": {