@codeyam/codeyam-cli 0.1.0-staging.a890816 → 0.1.0-staging.ae0de75

package/codeyam-cli/templates/skills/codeyam-memory/scripts/holistic-analysis/deprecated-prompt.md

@@ -0,0 +1,100 @@
+# Deprecated Pattern Analysis
+
+You are analyzing a codebase for **deprecated patterns** — situations where two approaches to the same problem coexist, with one fading in favor of another. These create confusion because a coding agent reading locally may follow the old pattern.
+
+## Input
+
+Read the scan data from `/tmp/codeyam-memory/deprecated-scan.json`. It contains:
+
+- `dependencies`: All npm dependency names from the project
+- `explicit_markers`: Lines containing `@deprecated`, `// legacy`, etc., with file, line number, and text
+- `git_recency`: Per-dependency counts of `recent_imports` (last 3 months) vs `old_imports` (3–12 months ago)
+
+## Analysis Steps
+
+### 1. Dependency Overlap Analysis
+
+Review the full dependency list and identify pairs or groups that serve **overlapping purposes**. Use your domain knowledge of the npm ecosystem — don't rely on name similarity alone.
+
+Common overlap categories:
+
+- **ORMs / query builders**: knex, kysely, prisma, drizzle, typeorm, sequelize, supabase-js (when used for queries)
+- **Date libraries**: moment, dayjs, date-fns, luxon
+- **HTTP clients**: axios, got, node-fetch, ky, superagent, undici
+- **State management**: redux, zustand, jotai, recoil, mobx, valtio
+- **Schema validation**: zod, yup, joi, ajv, io-ts, superstruct, valibot
+- **CSS-in-JS / styling**: styled-components, emotion, tailwind, vanilla-extract, stitches
+- **Testing**: jest, vitest, mocha, ava
+- **Bundlers**: webpack, vite, esbuild, rollup, parcel, turbopack
+- **Logging**: winston, pino, bunyan, log4js
+
+Also look for:
+
+- Internal packages that wrap the same underlying library differently
+- Old utility files alongside newer replacements
+
+### 2. Cross-Reference with Git Recency
+
+For each overlapping pair you identified, check the `git_recency` data:
+
+- Is one dependency's import count **growing** (more recent than old) while the other is **fading** (fewer recent than old)?
+- A clear growth-vs-fade pattern confirms a migration in progress.
+- If both are stable or both are growing, it may be intentional coexistence rather than a migration.
+
+### 3. Cross-Reference with Explicit Markers
+
+Check if any `@deprecated` or `// legacy` markers corroborate your dependency findings:
+
+- A marker on code that imports the fading dependency strengthens the signal
+- A marker on a wrapper/utility that abstracts one of the approaches is strong evidence
+
+### 4. Find Remaining Callsites
+
+For each confirmed deprecated pattern, use Grep to find all files still importing or using the old dependency/pattern. Count the callsites to assess migration completeness.
+
+Search patterns:
+
+```
+from ['"]<old-dep>
+require(['"]<old-dep>
+import <old-dep>
+```
+
+### 5. Assess Severity
+
+- **high**: Active migration with significant remaining old callsites (>10 files), or explicit deprecation markers present
+- **medium**: Clear trend in git recency but no explicit markers and fewer remaining callsites
+- **low**: Slight trend, possibly intentional coexistence
+
+## Output
+
+Return your findings as a JSON code block in your response, using this format:
+
+```json
+{
+  "findings": [
+    {
+      "type": "deprecated-pattern",
+      "old_pattern": "descriptive name of the old approach",
+      "new_pattern": "descriptive name of the new approach",
+      "evidence": "concise summary of the evidence (git recency numbers, markers found)",
+      "files_still_using_old": ["path/to/file1.ts", "path/to/file2.ts"],
+      "severity": "high|medium|low",
+      "suggested_rule_paths": ["src/relevant/**/*.ts"]
+    }
+  ],
+  "stats": {
+    "deps_analyzed": 0,
+    "overlapping_pairs_found": 0,
+    "confirmed_deprecated": 0
+  }
+}
+```
+
+After the JSON block, return a **brief one-paragraph summary** of your findings. Include the number of confirmed deprecated patterns and the highest-severity finding.
+
+## Important Notes
+
+- Be conservative: only flag patterns where there is clear evidence of transition, not just the presence of two similar libraries
+- Some projects intentionally use multiple tools in the same category (e.g., jest for unit tests and playwright for e2e) — that's not deprecation
+- Focus on patterns that would **mislead a coding agent** — if both approaches are valid and documented, it may not need a rule

package/codeyam-cli/templates/skills/codeyam-memory/scripts/holistic-analysis/detect-deprecated-patterns.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Gathers deprecation signals from package.json, source markers, and git history.
+# Outputs structured JSON to /tmp/codeyam-memory/deprecated-scan.json
+
+set -euo pipefail
+
+OUTPUT_DIR="/tmp/codeyam-memory"
+OUTPUT_FILE="$OUTPUT_DIR/deprecated-scan.json"
+mkdir -p "$OUTPUT_DIR"
+
+# --- Dependency scan ---
+# Collect all dependency names from package.json files (root + workspace packages)
+deps_json="[]"
+while IFS= read -r pkg_file; do
+  # Extract dependency names from both dependencies and devDependencies
+  file_deps=$(jq -r '(.dependencies // {} | keys[]) , (.devDependencies // {} | keys[])' "$pkg_file" 2>/dev/null || true)
+  if [ -n "$file_deps" ]; then
+    deps_json=$(echo "$deps_json" | jq --arg d "$file_deps" '. + ($d | split("\n") | map(select(. != "")))')
+  fi
+done < <(find . -name "package.json" -not -path "*/node_modules/*" -not -path "*/dist/*" -not -path "*/.next/*" 2>/dev/null)
+
+# Deduplicate
+deps_json=$(echo "$deps_json" | jq 'unique')
+
+# --- Explicit marker scan ---
+markers_json="[]"
+marker_output=$(rg -n "@deprecated|// legacy|// deprecated|// old approach|TODO.*deprecat|FIXME.*deprecat" \
+  --type ts --type js \
+  --glob '!node_modules' --glob '!dist' --glob '!build' --glob '!.next' \
+  -C 2 2>/dev/null || true)
+
+if [ -n "$marker_output" ]; then
+  # Parse ripgrep output into JSON entries
+  markers_json=$(echo "$marker_output" | awk -F: '
+    /^[^-].*:[0-9]+:/ {
+      file = $1
+      line = $2
+      # Rejoin the rest as text (handles colons in content)
+      text = ""
+      for (i = 3; i <= NF; i++) {
+        text = (text == "" ? $i : text ":" $i)
+      }
+      gsub(/^[ \t]+/, "", text)
+      gsub(/"/, "\\\"", text)
+      gsub(/\t/, " ", text)
+      printf "{\"file\":\"%s\",\"line\":%s,\"text\":\"%s\"},\n", file, line, text
+    }
+  ' | sed '$ s/,$//' | awk 'BEGIN{print "["} {print} END{print "]"}')
+
+  # Validate JSON — fall back to empty array if malformed
+  if ! echo "$markers_json" | jq empty 2>/dev/null; then
+    markers_json="[]"
+  fi
+fi
+
+# --- Git recency comparison ---
+# Extract all import lines from git patches in two passes (recent + old), then count per-dep
+recency_json="{}"
+dep_count=$(echo "$deps_json" | jq length)
+
+if [ "$dep_count" -gt 0 ]; then
+  RECENT_IMPORTS="$OUTPUT_DIR/recent-imports.txt"
+  OLD_IMPORTS="$OUTPUT_DIR/old-imports.txt"
+
+  # Single git log pass per time window — extract only import lines
+  git log --since="3 months ago" -p -- '*.ts' '*.tsx' '*.js' '*.jsx' 2>/dev/null \
+    | grep -oE "from ['\"][^'\"]+['\"]" > "$RECENT_IMPORTS" 2>/dev/null || true
+  git log --since="12 months ago" --until="3 months ago" -p -- '*.ts' '*.tsx' '*.js' '*.jsx' 2>/dev/null \
+    | grep -oE "from ['\"][^'\"]+['\"]" > "$OLD_IMPORTS" 2>/dev/null || true
+
+  for dep in $(echo "$deps_json" | jq -r '.[]'); do
+    # Skip short names that would match too broadly
+    if [ ${#dep} -lt 3 ]; then
+      continue
+    fi
+
+    recent=$(grep -c "from ['\"]${dep}" "$RECENT_IMPORTS" 2>/dev/null || true)
+    recent=${recent:-0}
+    old=$(grep -c "from ['\"]${dep}" "$OLD_IMPORTS" 2>/dev/null || true)
+    old=${old:-0}
+
+    if [ "$recent" -gt 0 ] || [ "$old" -gt 0 ]; then
+      recency_json=$(echo "$recency_json" | jq \
+        --arg dep "$dep" \
+        --argjson recent "$recent" \
+        --argjson old "$old" \
+        '. + {($dep): {"recent_imports": $recent, "old_imports": $old}}')
+    fi
+  done
+
+  rm -f "$RECENT_IMPORTS" "$OLD_IMPORTS"
+fi
+
+# --- Assemble final output ---
+jq -n \
+  --argjson dependencies "$deps_json" \
+  --argjson explicit_markers "$markers_json" \
+  --argjson git_recency "$recency_json" \
+  '{
+    dependencies: $dependencies,
+    explicit_markers: $explicit_markers,
+    git_recency: $git_recency
+  }' > "$OUTPUT_FILE"
+
+echo "Deprecated pattern scan complete: $OUTPUT_FILE"
+echo "  Dependencies found: $(echo "$deps_json" | jq length)"
+echo "  Explicit markers found: $(echo "$markers_json" | jq length)"
+echo "  Deps with git activity: $(echo "$recency_json" | jq 'length')"

package/codeyam-cli/templates/skills/codeyam-memory/scripts/holistic-analysis/find-exports.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Indexes the project's public API surface by finding all exports.
+# Outputs structured JSON to /tmp/codeyam-memory/exports-scan.json
+
+set -euo pipefail
+
+OUTPUT_DIR="/tmp/codeyam-memory"
+OUTPUT_FILE="$OUTPUT_DIR/exports-scan.json"
+mkdir -p "$OUTPUT_DIR"
+
+# Find all export declarations, excluding noise directories and .d.ts files
+export_output=$(rg -n "^export (function|const|class|default|async function|type|interface|enum)" \
+  --type ts --type js \
+  --glob '!node_modules' --glob '!dist' --glob '!build' --glob '!.next' \
+  --glob '!*.d.ts' --glob '!*.map' \
+  2>/dev/null || true)
+
+if [ -z "$export_output" ]; then
+  # No exports found — output empty structure
+  jq -n '{files: {}, stats: {total_files: 0, total_exports: 0}}' > "$OUTPUT_FILE"
+  echo "Export scan complete: $OUTPUT_FILE (no exports found)"
+  exit 0
+fi
+
+# Parse ripgrep output into JSON grouped by file
+# Format: file:line:text
+files_json=$(echo "$export_output" | awk -F: '
+{
+  file = $1
+  line = $2
+  # Rejoin rest as text
+  text = ""
+  for (i = 3; i <= NF; i++) {
+    text = (text == "" ? $i : text ":" $i)
+  }
+  # Trim leading whitespace
+  gsub(/^[ \t]+/, "", text)
+  # Escape quotes for JSON
+  gsub(/"/, "\\\"", text)
+  gsub(/\t/, " ", text)
+  printf "%s\t%s\t%s\n", file, line, text
+}' | jq -Rsn '
+  [inputs | split("\n") | .[] | select(. != "") |
+    split("\t") | select(length >= 3) |
+    {file: .[0], line: (.[1] | tonumber), text: .[2]}
+  ] |
+  group_by(.file) |
+  reduce .[] as $group ({};
+    . + {($group[0].file): [$group[] | {line: .line, text: .text}]}
+  )
+')
+
+# Compute stats
+total_files=$(echo "$files_json" | jq 'length')
+total_exports=$(echo "$files_json" | jq '[.[] | length] | add // 0')
+
+# Assemble final output
+jq -n \
+  --argjson files "$files_json" \
+  --argjson total_files "$total_files" \
+  --argjson total_exports "$total_exports" \
+  '{
+    files: $files,
+    stats: {total_files: $total_files, total_exports: $total_exports}
+  }' > "$OUTPUT_FILE"
+
+echo "Export scan complete: $OUTPUT_FILE"
+echo "  Files with exports: $total_files"
+echo "  Total exports: $total_exports"

package/codeyam-cli/templates/skills/codeyam-memory/scripts/holistic-analysis/misleading-api-prompt.md

@@ -0,0 +1,117 @@
+# Misleading API Analysis
+
+You are analyzing a codebase for **misleading APIs** — exported functions whose names promise one thing but whose implementations do another. These are dangerous because a coding agent reading the function signature will make incorrect assumptions about behavior.
+
+## Input
+
+Read the export index from `/tmp/codeyam-memory/exports-scan.json`. It contains:
+
+- `files`: Object keyed by file path, each containing an array of `{line, text}` export declarations
+- `stats`: `total_files` and `total_exports` counts
+
+## Analysis Steps
+
+### 1. Triage by Name Pattern
+
+Scan all export names and prioritize **pure-sounding** functions — names that imply no side effects or predictable behavior:
+
+**Highest priority** (names suggesting pure computation):
+
+- `get*`, `compute*`, `calculate*`, `derive*`, `extract*`
+- `is*`, `has*`, `check*`, `can*`
+- `parse*`, `format*`, `transform*`, `convert*`
+- `to*`, `from*`, `create*` (when suggesting a factory)
+- `validate*`, `verify*`
+
+**Medium priority** (names suggesting single responsibility):
+
+- `save*`, `update*`, `delete*`, `remove*` — check for hidden secondary effects
+- `send*`, `notify*`, `emit*` — check for unexpected mutations
+- `init*`, `setup*`, `configure*` — check for non-obvious global state changes
+
+### 2. Deep Read Suspicious Exports
+
+For each pure-sounding or single-responsibility export, use the Read tool to read the **full function implementation** (not just 30 lines — read until the function ends). Look for these red flags:
+
+**Side effects in "pure" functions:**
+
+- Writes to external state (database, cache, filesystem, global variables)
+- Network calls (fetch, HTTP requests, WebSocket messages)
+- Logging that includes sensitive data or business logic decisions
+- Event emission or pub/sub publishing
+
+**Input mutation:**
+
+- Modifying objects/arrays passed as arguments (when the name doesn't suggest mutation)
+- Reassigning properties on `this` in methods that sound like getters
+
+**Silent error swallowing:**
+
+- `catch` blocks that return default values instead of throwing or propagating
+- `try/catch` around critical operations where the function signature suggests it will throw on failure
+- Optional chaining (`?.`) chains that silently return `undefined` for important data
+
+**Unexpected returns:**
+
+- Function name suggests returning one type but actually returns something different
+- `get*` functions that return `null` or `undefined` instead of throwing when the entity doesn't exist
+- Boolean-named functions (`is*`, `has*`) that return non-boolean values
+
+**Hidden coupling:**
+
+- Functions that read from or write to module-level state
+- Functions that depend on call order (must call A before B)
+- Functions that modify shared caches or memoization stores
+
+### 3. Scan Non-Pure Exports Too
+
+Quickly scan action-oriented exports (`save*`, `update*`, etc.) at a glance for **hidden secondary effects**:
+
+- `saveUser()` that also sends a welcome email
+- `deleteProject()` that also archives data elsewhere
+- `updateConfig()` that also restarts a service
+
+### 4. Count Callsites
+
+For each finding, use Grep to count how many files import or call the misleading function. More callsites = higher impact.
+
+### 5. Assess Severity
+
+- **high**: The mismatch could cause data corruption, silent failures, security issues, or affects >10 callsites
+- **medium**: The mismatch leads to unexpected behavior that would cause bugs, or affects 3–10 callsites
+- **low**: Minor naming inconsistency, affects few callsites, unlikely to cause bugs
+
+## Output
+
+Return your findings as a JSON code block in your response, using this format:
+
+```json
+{
+  "findings": [
+    {
+      "type": "misleading-api",
+      "function": "functionName",
+      "file": "path/to/file.ts",
+      "name_implies": "what the name suggests the function does",
+      "actually_does": "what it actually does (with specific line numbers for the divergent behavior)",
+      "severity": "high|medium|low",
+      "callsite_count": 0
+    }
+  ],
+  "stats": {
+    "exports_scanned": 0,
+    "deep_reads": 0,
+    "findings_count": 0
+  }
+}
+```
+
+After the JSON block, return a **brief one-paragraph summary** of your findings. Include the number of findings and the most notable misleading API discovered.
+
+## Important Notes
+
+- **Read full implementations** — don't just look at the first few lines. Side effects often live at the end of functions or in helper calls.
+- Be conservative with "low" severity findings — only flag things that would actually mislead a coding agent into writing incorrect code
+- **Skip type exports** (type, interface, enum) — these can't have behavioral mismatches
+- **Skip trivial getters** that just return a property — focus on functions with actual logic
+- When a function delegates to a helper, read the helper too if the function name implies purity but the helper name suggests side effects

package/codeyam-cli/templates/skills/codeyam-memory/scripts/session-mining/analyze-prompt.md

@@ -0,0 +1,46 @@
+# Session Log Analysis Prompt
+
+You are analyzing a filtered Claude Code session transcript to find instances where Claude got confused about **this specific codebase**. The transcript has been preprocessed — each line is a JSON object with `type` ("user" or "assistant"), `ts` (timestamp), and `content`.
+
+## Your Task
+
+Read the session file provided and identify moments where Claude demonstrated confusion that a `.claude/rules/` rule could have prevented.
+
+## Signal Types to Detect
+
+1. **USER_CORRECTION** — The user corrects Claude's approach, code, or assumption. Look for: "no, that's not how...", "actually...", "you need to use X not Y", "that's wrong", explicit disagreement.
+
+2. **RE_EDIT** — Claude edits the same file multiple times in quick succession, indicating the first attempt was wrong. Look for: multiple Edit/Write tool calls targeting the same file path with different content.
+
+3. **FAILED_PIVOT** — A tool call fails (test failure, bash error, type error) and Claude switches to a different approach. Look for: error in tool result followed by a new strategy in the next assistant message.
+
+4. **WRONG_ASSUMPTION** — Claude's thinking or text reveals an incorrect assumption about the codebase. Look for: statements that contradict later evidence, "I assumed...", reasoning that turns out wrong.
+
+5. **TRIBAL_KNOWLEDGE** — The user provides context Claude didn't have but needed. Look for: the user explaining how something works, why something is the way it is, historical context, non-obvious conventions.
+
+6. **APPROACH_PIVOT** — Claude abandons a call chain mid-stream and tries something completely different (without an explicit error triggering it). Look for: sudden topic/strategy shifts in assistant messages.
+
+## Rules for Reporting
+
+- **Only report codebase-specific confusion.** Generic programming mistakes (typos, syntax errors, forgetting imports for standard libraries) are NOT worth reporting.
+- **Only report findings where a `.claude/rules/` rule would prevent the confusion.** If the confusion is situational or one-off, skip it.
+- **Maximum 5 findings per session.** Prioritize the strongest, most rule-worthy signals.
+- **Be precise about file paths.** If the confusion relates to specific files, include them.
+
+## Output Format
+
+Return a JSON array (no markdown fences, no explanation outside the array). Each element:
+
+```json
+{
+  "signal": "USER_CORRECTION | RE_EDIT | FAILED_PIVOT | WRONG_ASSUMPTION | TRIBAL_KNOWLEDGE | APPROACH_PIVOT",
+  "summary": "One sentence describing what went wrong",
+  "evidence": "Brief quote or paraphrase from the session proving this happened",
+  "file_path": "path/to/relevant/file.ts or null if not file-specific",
+  "topic": "kebab-case-topic-label",
+  "rule_worthy": true,
+  "rule_worthy_reason": "Why a rule would prevent this from recurring"
+}
+```
+
+If the session contains no codebase-specific confusion worth documenting, return an empty array: `[]`

package/codeyam-cli/templates/skills/codeyam-memory/scripts/session-mining/cleanup.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Removes cached preprocessed session files.
+set -euo pipefail
+
+OUTPUT_DIR="/tmp/cc-session-analysis"
+
+if [ -d "$OUTPUT_DIR" ]; then
+  rm -rf "$OUTPUT_DIR"
+  echo "Cleaned up $OUTPUT_DIR"
+else
+  echo "Nothing to clean up ($OUTPUT_DIR does not exist)"
+fi

package/codeyam-cli/templates/skills/codeyam-memory/scripts/session-mining/filter.jq

@@ -0,0 +1,45 @@
+# Session log filter for codeyam-memory skill.
+# Strips progress/system/queue records, compresses tool inputs to 300 chars,
+# tool results to 500 chars, thinking to 1000 chars. Output is compact JSONL.
+
+select(.type == "user" or .type == "assistant") |
+if .type == "assistant" then
+  {
+    type: "assistant",
+    ts: .timestamp,
+    content: [
+      (.message.content[]? |
+        if .type == "text" then
+          {t: "text", text}
+        elif .type == "thinking" then
+          {t: "think", thinking: (.thinking // "" | if length > 1000 then (.[0:1000] + "...[truncated]") else . end)}
+        elif .type == "tool_use" then
+          {t: "tool", name, input: (.input | tostring | if length > 300 then .[0:300] + "..." else . end)}
+        else empty
+        end
+      )
+    ]
+  }
+elif .type == "user" then
+  {
+    type: "user",
+    ts: .timestamp,
+    content: (
+      if (.message.content | type) == "string" then
+        .message.content
+      elif (.message.content | type) == "array" then
+        [.message.content[]? |
+          if .type == "tool_result" then
+            {t: "result", id: .tool_use_id, err: (.is_error // false),
+             content: (.content | tostring | if length > 500 then .[0:500] + "...[truncated]" else . end)}
+          else
+            {t: "msg", text: (. | tostring | if length > 500 then .[0:500] + "...[truncated]" else . end)}
+          end
+        ]
+      else
+        (.message.content | tostring | if length > 500 then .[0:500] + "...[truncated]" else . end)
+      end
+    )
+  }
+else empty
+end

package/codeyam-cli/templates/skills/codeyam-memory/scripts/session-mining/preprocess.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# Preprocesses Claude Code session logs for the codeyam-memory skill.
+#
+# - Finds JSONL session files (>=10KB, last 30 days)
+# - Excludes the current active session
+# - Runs jq filter for 5-50x compression
+# - Caches results in /tmp/cc-session-analysis/
+# - Prints filtered file paths to stdout (one per line)
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FILTER="$SCRIPT_DIR/filter.jq"
+OUTPUT_DIR="/tmp/cc-session-analysis"
+MIN_SIZE=10240  # 10KB
+MAX_AGE_DAYS=30
+MAX_SESSIONS=30  # Diminishing returns past this; keeps agent fleet manageable
+JQ_TIMEOUT=30    # Seconds — skip files that take longer than this to filter
+
+# --- Dependency check ---
+if ! command -v jq &>/dev/null; then
+  echo "Error: jq is required but not installed." >&2
+  echo "  macOS:  brew install jq" >&2
+  echo "  Ubuntu: sudo apt-get install jq" >&2
+  echo "  Other:  https://jqlang.github.io/jq/download/" >&2
+  exit 1
+fi
+
+# --- Compute Claude project directory ---
+PROJECT_DIR="$PWD"
+# Claude Code replaces both / and . with - in the project hash
+PROJECT_HASH=$(echo "$PROJECT_DIR" | sed 's|[/.]|-|g')
+SESSION_DIR="$HOME/.claude/projects/$PROJECT_HASH"
+
+if [ ! -d "$SESSION_DIR" ]; then
+  echo "No Claude session directory found at $SESSION_DIR" >&2
+  echo "This project may not have any Claude Code session history." >&2
+  exit 0
+fi
+
+# --- Find session files ---
+mkdir -p "$OUTPUT_DIR"
+
+# Collect eligible session files: >=10KB, modified within last 30 days, .jsonl extension
+# Sort by mtime (newest first) so the cap keeps the most recent sessions
+ALL_SESSIONS=()
+while IFS= read -r file; do
+  ALL_SESSIONS+=("$file")
+done < <(find "$SESSION_DIR" -maxdepth 1 -name "*.jsonl" -size +"$MIN_SIZE"c -mtime -"$MAX_AGE_DAYS" -print0 2>/dev/null \
+  | xargs -0 stat -f "%m %N" 2>/dev/null \
+  | sort -rn \
+  | awk '{print $2}')
+
+if [ ${#ALL_SESSIONS[@]} -eq 0 ]; then
+  exit 0
+fi
+
+# Cap to most recent N sessions
+SESSIONS=("${ALL_SESSIONS[@]:0:$MAX_SESSIONS}")
+if [ ${#ALL_SESSIONS[@]} -gt "$MAX_SESSIONS" ]; then
+  echo "Note: ${#ALL_SESSIONS[@]} sessions found, capping to $MAX_SESSIONS most recent" >&2
+fi
+
+# --- Exclude current active session ---
+# The newest file by mtime is likely the current session.
+# If CLAUDE_SESSION_ID is set, use that for a more precise match.
+NEWEST_FILE=""
+NEWEST_MTIME=0
+for file in "${SESSIONS[@]}"; do
+  mtime=$(stat -f "%m" "$file" 2>/dev/null || stat -c "%Y" "$file" 2>/dev/null || echo "0")
+  if [ "$mtime" -gt "$NEWEST_MTIME" ]; then
+    NEWEST_MTIME="$mtime"
+    NEWEST_FILE="$file"
+  fi
+done
+
+ACTIVE_SESSION=""
+if [ -n "${CLAUDE_SESSION_ID:-}" ]; then
+  for file in "${SESSIONS[@]}"; do
+    if [[ "$(basename "$file" .jsonl)" == "$CLAUDE_SESSION_ID" ]]; then
+      ACTIVE_SESSION="$file"
+      break
+    fi
+  done
+fi
+# Fall back to newest file if no env var match
+if [ -z "$ACTIVE_SESSION" ]; then
+  ACTIVE_SESSION="$NEWEST_FILE"
+fi
+
+# --- Process each session ---
+for file in "${SESSIONS[@]}"; do
+  # Skip active session
+  if [ "$file" = "$ACTIVE_SESSION" ]; then
+    continue
+  fi
+
+  uuid=$(basename "$file" .jsonl)
+  filtered="$OUTPUT_DIR/${uuid}.filtered.jsonl"
+
+  # Check cache: skip if filtered file exists and has a valid sentinel
+  if [ -f "$filtered" ]; then
+    first_line=$(head -1 "$filtered" 2>/dev/null || true)
+    if echo "$first_line" | jq -e '.processed_at' &>/dev/null; then
+      echo "$filtered"
+      continue
+    fi
+  fi
+
+  # Run jq filter
+  source_size=$(stat -f "%z" "$file" 2>/dev/null || stat -c "%s" "$file" 2>/dev/null || echo "0")
+  sentinel=$(printf '{"processed_at":"%s","source_size":%s}' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$source_size")
+
+  # Write sentinel as first line, then filtered content (with timeout)
+  jq_exit=0
+  {
+    echo "$sentinel"
+    if command -v timeout &>/dev/null; then
+      timeout "$JQ_TIMEOUT" jq -c -f "$FILTER" "$file" 2>/dev/null
+    elif command -v gtimeout &>/dev/null; then
+      gtimeout "$JQ_TIMEOUT" jq -c -f "$FILTER" "$file" 2>/dev/null
+    else
+      jq -c -f "$FILTER" "$file" 2>/dev/null
+    fi
+  } > "$filtered" || jq_exit=$?
+
+  if [ "$jq_exit" -eq 124 ]; then
+    echo "Warning: jq timed out after ${JQ_TIMEOUT}s on $(basename "$file") — skipping" >&2
+    rm -f "$filtered"
+    continue
+  fi
+
+  # Only output if the file has content beyond the sentinel
+  line_count=$(wc -l < "$filtered" | tr -d ' ')
+  if [ "$line_count" -gt 1 ]; then
+    echo "$filtered"
+  else
+    rm -f "$filtered"
+  fi
+done

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@codeyam/codeyam-cli",
-  "version": "0.1.0-staging.a890816",
+  "version": "0.1.0-staging.ae0de75",
   "description": "Local development CLI for CodeYam analysis",
   "type": "module",
   "bin": {
     "codeyam": "./codeyam-cli/src/codeyam-cli.js"
   },
   "scripts": {
-    "postinstall": "node ./scripts/finalize-analyzer.cjs && chmod +x ./node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper 2>/dev/null; chmod +x ./node_modules/node-pty/prebuilds/darwin-x64/spawn-helper 2>/dev/null; true"
+    "postinstall": "node ./scripts/npm-post-install.cjs && [ -f ./node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper ] && chmod +x ./node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper; [ -f ./node_modules/node-pty/prebuilds/darwin-x64/spawn-helper ] && chmod +x ./node_modules/node-pty/prebuilds/darwin-x64/spawn-helper; true"
   },
   "dependencies": {
     "@anthropic-ai/claude-code": "^2.1.7",

package/scripts/npm-post-install.cjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install script — we used to finalize the CodeYam analyzer here,
+ * but that is now deferred to the `codeyam setup-simulations` step.
+ */
+
+console.error('');
+console.error('  CodeYam CLI installed successfully!');
+console.error('');
+console.error("    Type 'codeyam' in your project directory to get started.");
+console.error('');