@codeyam/codeyam-cli 0.1.0-staging.036391e → 0.1.0-staging.039fa00

package/codeyam-cli/templates/skills/codeyam-editor/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: codeyam-editor
+autoApprove: true
+description: CodeYam Editor Mode — scaffold a project and build code + data scenarios together
+---
+
+# CodeYam Editor Mode
+
+You are in **Editor Mode**. The user sees a split-screen: this terminal on the left, live preview on the right.
+
+## CRITICAL: How This Works
+
+You MUST follow a step-by-step workflow driven by `codeyam editor` commands. Each command tells you exactly what to do next. **You do NOT have all the instructions upfront** — the commands provide them incrementally.
+
+**Your first action:** Run `codeyam editor`.
+
+**The rule:** After completing what a command tells you to do, run the NEXT command it specifies. The commands are your instructions — follow them one at a time.
+
+## The Cycle
+
+Every feature follows 12 gated steps:
+
+```
+codeyam editor      → Setup (if new) or cycle overview
+codeyam editor 1    → Plan the feature (confirm with user)
+codeyam editor 2    → Build a working prototype fast
+codeyam editor 3    → Confirm prototype with user
+codeyam editor 4    → Plan extraction (read code, list everything to extract)
+codeyam editor 5    → Execute extraction (TDD for functions, extract components)
+codeyam editor 6    → Record functions in glossary
+codeyam editor 7    → Analyze and verify components
+codeyam editor 8    → Create app-level scenarios
+codeyam editor 9    → Create user-persona scenarios
+codeyam editor 10   → Verify screenshots and check for errors
+codeyam editor 11   → Create/update journal entry
+codeyam editor 12   → Present summary, get final approval
+```
+
+**You MUST run each command and follow its checklist before moving to the next.** Steps 1, 3, and 12 require user confirmation. After step 12, loop back to step 1.
+
+## Key Rules
+
+- **Run the commands** — they ARE your instructions, not suggestions
+- **Every feature gets scenarios** — this is the core value of CodeYam
+- **Always scaffold with a database** (Prisma + SQLite)
+- **Build real API routes** — the proxy handles scenario data transparently
+- **Start the dev server via the CodeYam API** — it handles proxy setup automatically
+- **Verify the preview after changes** — check the dev server URL, not the proxy
+
+## Quick Reference
+
+```bash
+# Register scenario (auto-captures screenshot)
+curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/editor-register-scenario \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"...","description":"...","mockData":{"routes":{"/api/...":{"body":[...]}}}}'
+
+# Journal entry (one per feature, references scenario names)
+curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/editor-journal-entry \
+  -H 'Content-Type: application/json' \
+  -d '{"title":"...","type":"feature","description":"...","scenarios":["..."]}'
+
+# Refresh preview
+curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/dev-mode-preview
+
+# Restart dev server (only for config/dependency changes)
+curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/editor-dev-server \
+  -H 'Content-Type: application/json' -d '{"action":"restart"}'
+```

package/codeyam-cli/templates/{codeyam:memory.md → skills/codeyam-memory/SKILL.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:memory
+name: codeyam-memory
 autoApprove: true
 description: |
   Generate and maintain Claude Rules for your codebase based on thorough analysis.
@@ -13,19 +13,14 @@ This skill helps you generate and maintain Claude Rules (`.claude/rules/`) that
 
 ## Core Principle: Document Confusion, Not Information
 
-**Good rules** explain things that are NOT obvious from reading the code:
+**Valuable rules** capture knowledge that reading the code alone wouldn't reveal:
 
 - 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)
+Skip documenting things Claude can determine by reading code: function signatures, type definitions, directory structure, and common patterns.
 
 ## When to Use This Skill
 
@@ -41,7 +36,9 @@ Check if this is the first time running memory.
 
 ### 1A. Add Documentation Section to CLAUDE.md
 
-If CLAUDE.md doesn't contain a "When Confused / With Mistakes" section, add close to the top:
+If CLAUDE.md already contains a "Documenting Confusion / Mistakes" section, skip this step entirely.
+
+Otherwise, add **only** the section below — do not modify or add any other content to CLAUDE.md. If CLAUDE.md doesn't exist, create it with just a `# Project` heading followed by this section:
 
 ```markdown
 ## Continuous Documentation
@@ -61,6 +58,8 @@ It is very important to document any tribal knowledge, complex architectural dec
 Please see `.codeyam/rules/instructions.md` for guidance.
 ```
 
+**Important:** Do not add project descriptions, architecture summaries, or any other content to CLAUDE.md. Only add the exact section above.
+
 ### 1B. Verify Instructions File
 
 Check that `.codeyam/rules/instructions.md` exists (it should be created during `codeyam init`). If missing, copy it from `codeyam-cli/templates/rules-instructions.md`.
@@ -209,6 +208,215 @@ Prioritize areas with stronger confusion signals:
 
 Focus your documentation efforts on areas with the highest confusion scores.
 
+Holistic source analysis signals (from the Holistic Source Analysis phase below) also feed into this scoring. Session mining signals (from the Session Log Mining phase below) feed into this same table.
+
+---
+
+## Phase 3B: Analysis Sizing & Menu
+
+Before running the expensive LLM-powered analysis phases, run the fast extraction scripts to gather sizing metrics and let the user choose which phases to run.
+
+### Step 1: Run fast extraction scripts (concurrent)
+
+Clear stale data from any previous run, then run all three scripts in parallel:
+
+```bash
+rm -rf /tmp/codeyam-memory/ /tmp/cc-session-analysis/
+```
+
+```bash
+bash .claude/skills/codeyam-memory/scripts/holistic-analysis/detect-deprecated-patterns.sh
+```
+
+```bash
+bash .claude/skills/codeyam-memory/scripts/holistic-analysis/find-exports.sh
+```
+
+```bash
+bash .claude/skills/codeyam-memory/scripts/session-mining/preprocess.sh 2>/dev/null
+```
+
+Capture the stdout of `preprocess.sh` — each line is a path to a filtered session file.
+
+### Step 2: Extract sizing metrics
+
+Use quick `jq` one-liners to extract counts — do NOT read the full JSON files into the main context:
+
+```bash
+jq '.dependencies | length' /tmp/codeyam-memory/deprecated-scan.json
+jq '.explicit_markers | length' /tmp/codeyam-memory/deprecated-scan.json
+jq '.stats.total_exports' /tmp/codeyam-memory/exports-scan.json
+jq '.stats.total_files' /tmp/codeyam-memory/exports-scan.json
+```
+
+The session count is the number of lines from `preprocess.sh` stdout.
+
+**Time estimate formulas:**
+
+| Phase                    | Formula                                 | Example                 |
+| ------------------------ | --------------------------------------- | ----------------------- |
+| Holistic source analysis | `3 + (total_exports / 500)` min, cap 12 | 3,470 exports → ~10 min |
+| Session log mining       | `1 + (sessions × 0.25)` min, cap 12     | 25 sessions → ~7 min    |
+
+### Step 3: Present the menu
+
+Use `AskUserQuestion` with `multiSelect: true`. Include actual numbers from Step 2:
+
+> **Which additional analysis phases would you like to run?**
+>
+> 📦 **Holistic Source Analysis** — {exports} exports across {files} files, {deps} dependencies, {markers} deprecation markers. Estimated: ~{N} min
+>
+> 💬 **Session Log Mining** — {sessions} qualifying sessions found. Estimated: ~{N} min
+
+Options (as `multiSelect: true`):
+
+- **Holistic Source Analysis (~N min)** — "Deep-read exports to find misleading APIs and deprecated patterns"
+- **Session Log Mining (~N min)** — "Mine Claude session history for confusion signals"
+- **Skip both** — "Proceed with git archaeology results only"
+
+Omit any option where the data count is zero (e.g., if no sessions qualify, don't show the session mining option). If both counts are zero, skip the menu entirely and proceed to Phase 4.
+
+### Step 4: Execute selected phases
+
+Based on the user's selection:
+
+- **Holistic Source Analysis selected:** Jump to the "Holistic Source Analysis" section below, starting at **Step 2** (scripts already ran in Step 1 above).
+- **Session Log Mining selected:** Jump to the "Session Log Mining" section below, starting at **Step 2** (preprocessing already ran in Step 1 above). Use the session file paths captured in Step 1.
+- **Both selected:** Run both, starting each at Step 2.
+- **Skip both:** Proceed directly to Phase 4.
+
+### Step 5: Cleanup
+
+Regardless of what the user selected, clean up temporary files before proceeding to Phase 4:
+
+```bash
+rm -rf /tmp/codeyam-memory/ /tmp/cc-session-analysis/
+```
+
+---
+
+## Additional Analysis Phase: Holistic Source Analysis
+
+Holistic analysis reads the codebase cross-cuttingly to find **latent confusion** — problems
+that haven't caused bugs yet but will mislead a future agent reading code locally.
+
+### Prerequisites
+
+- Project must contain `.ts`, `.tsx`, `.js`, or `.jsx` source files
+- If no source files are found, skip this phase entirely
+
+### Step 1: Run extraction scripts
+
+Handled by Phase 3B. Proceed to Step 2.
+
+### Step 2: Launch analysis subagents (concurrent)
+
+Read the prompt templates and launch both as Task agents concurrently. **Do NOT read the
+scan data into the main context** — it can be hundreds of KB. Each subagent reads its own
+data file via the Read tool.
+
+1. **Deprecated Pattern agent** — Read `.claude/skills/codeyam-memory/scripts/holistic-analysis/deprecated-prompt.md` for the
+   prompt template. Launch as a foreground Task agent (model: sonnet) with the prompt template
+   content. The agent reads `/tmp/codeyam-memory/deprecated-scan.json` itself, uses Grep to
+   find remaining callsites, and returns its findings JSON in the response.
+
+2. **Misleading API agent** — Read `.claude/skills/codeyam-memory/scripts/holistic-analysis/misleading-api-prompt.md` for the
+   prompt template. Launch as a foreground Task agent (model: sonnet) with the prompt template
+   content. The agent reads `/tmp/codeyam-memory/exports-scan.json` itself, uses Read to
+   inspect suspicious functions, and returns its findings JSON in the response.
+
+Both agents return their findings JSON and a brief summary directly in their response.
+
+**Context budget note:** The exports index alone can be 400KB+. Never read it into the main
+context. Subagents run as foreground Task agents and have full filesystem access including
+`/tmp/`.
+
+### Step 3: Integrate findings
+
+Parse the findings JSON from each subagent's response. For each finding:
+
+- **Deprecated patterns** get confusion score **4** (comparable to "workaround/hack" signal).
+  If an explicit `@deprecated` marker exists, bump to **5**.
+- **Misleading APIs** get confusion score **4** for medium severity, **6** for high severity
+  (where "high" means the mismatch could cause data corruption or silent failures).
+
+Add findings to the evidence pool alongside git archaeology results. They flow into
+Phase 4 (evidence-based user questions) and Phase 5 (rule generation) normally.
+
+### Step 4: Cleanup
+
+Handled by Phase 3B Step 5.
+
+---
+
+## Additional Analysis Phase: Session Log Mining
+
+This phase mines Claude Code session transcripts for empirical confusion: user corrections, wrong assumptions, re-edits, tribal knowledge gaps. It complements the git archaeology in Phase 2 with direct evidence from actual Claude sessions.
+
+### Step 1: Preprocess Sessions
+
+Handled by Phase 3B. Use the session file paths captured there.
+
+### Step 2: Launch Haiku Subagents
+
+Read the prompt template from `.claude/skills/codeyam-memory/scripts/session-mining/analyze-prompt.md`.
+
+For each filtered session file from Step 1:
+
+- If the file is **<200KB**: launch one Haiku Task agent
+- If the file is **>200KB**: chunk into ~200KB segments, launch one agent per chunk
+
+**Do NOT read session files into the main context** — they can be 20-40KB each and will
+exhaust the context window. Each subagent reads its own file via the Read tool. Each agent
+receives:
+
+1. The prompt template content
+2. The `/tmp/` file path to read (the agent reads it itself)
+3. Instruction to return a JSON array
+
+Launch agents in batches of **10** using the Task tool with `model: "haiku"`. **Use unique descriptions** for each agent (e.g., "Session mining batch 1 - session 1", "Session mining batch 1 - session 2", etc.; increment the batch number for each batch of 10). Wait for each batch to complete before launching the next. This keeps machine load manageable — a poweruser may have 30+ sessions qualifying.
+
+### Step 3: Collect and Validate Findings
+
+Parse each agent's response as JSON. Validate:
+
+- Must be an array
+- Each element must have `signal` and `summary` fields
+- `signal` must be one of: `USER_CORRECTION`, `RE_EDIT`, `FAILED_PIVOT`, `WRONG_ASSUMPTION`, `TRIBAL_KNOWLEDGE`, `APPROACH_PIVOT`
+
+If >50% of agents return invalid output, warn the user before continuing. Otherwise, silently skip invalid results.
+
+**Filter out environment-specific findings.** Discard any finding that relates to the developer's local machine setup rather than the project's codebase — e.g., bare repo checkout layouts, local tool versions, IDE configuration, shell aliases, filesystem paths, or permission issues. The rules we generate must be useful to _any_ developer cloning the repo, not just the one whose sessions we mined.
+
+### Step 4: Deduplicate Across Sessions
+
+Three-pass merge:
+
+1. **Cluster by `topic`** — group all findings with the same topic label
+2. **Rank within each cluster** — priority order: `USER_CORRECTION` > `TRIBAL_KNOWLEDGE` > `WRONG_ASSUMPTION` > `FAILED_PIVOT` > `RE_EDIT` > `APPROACH_PIVOT`
+3. **Count session occurrences** — add `session_count` to each merged finding
+
+Output: one merged finding per topic, with `session_count`, strongest signal type, and collected file paths.
+
+### Step 5: Feed into Phase 3 Scoring
+
+Additional scoring weights for session-mining signals:
+
+| Signal                              | Weight   |
+| ----------------------------------- | -------- |
+| User correction (session)           | 7        |
+| Tribal knowledge provided (session) | 6        |
+| Wrong assumption caught (session)   | 5        |
+| Re-edit of same file (session)      | 4        |
+| Failed-then-pivoted (session)       | 3        |
+| Appearing in 3+ sessions            | +3 bonus |
+
+These merge into the Phase 3 scoring table above. Session-mined findings then flow into Phase 4 (evidence-based questions) and Phase 5 (rule generation) alongside git archaeology findings.
+
+### Step 6: Cleanup
+
+Handled by Phase 3B Step 5.
+
 ---
 
 ## Phase 4: Ask Evidence-Based Questions
@@ -275,7 +483,7 @@ Before generating each rule, verify it passes these tests:
 
 **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 YES → the code is its own documentation — prefer keeping rules for non-derivable insights
 - 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?
@@ -283,6 +491,12 @@ Before generating each rule, verify it passes these tests:
 - If YES → definitely document it
 - If NO → reconsider its value
 
+**For holistic analysis findings**, the validation checks apply with these adjustments:
+
+- **Evidence check:** Satisfied by structural evidence from source analysis (e.g., "name implies pure computation but implementation writes to cache on line 47") rather than git commit history.
+- **Code-derivable check:** These findings ARE derived from code — but from a cross-cutting read that a local reader wouldn't perform. The rule is valuable if it captures insight that requires reading multiple files or tracing non-obvious call chains.
+- **Prevention check:** "Would this rule prevent a future agent from being misled?" rather than "would it have prevented a past commit?"
+
 ### Rule Quality Examples
 
 **✅ Good rule** (passes all tests):
@@ -301,7 +515,7 @@ This caused a bug where `entity` matched `entityCode` (siblings, not parent-chil
 - Not code-derivable: Code doesn't explain why boundary checking matters
 - Prevention: Would prevent future prefix-matching bugs
 
-**❌ Bad rule** (fails tests):
+**Compare with a weaker alternative** (fails the checks):
 
 ```markdown
 ## Running Tests
@@ -309,9 +523,7 @@ This caused a bug where `entity` matched `entityCode` (siblings, not parent-chil
 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
+- No confusion evidence, code-derivable, and wouldn't prevent future mistakes
 
 ### 5B. Rule File Guidelines
 
@@ -319,17 +531,13 @@ Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
    - Rule for `src/api/` → `.claude/rules/src/api/architecture.md`
    - Rule for testing patterns → `.claude/rules/testing-patterns.md`
 
-2. **Paths must be specific**
-   - Good: `paths: ['src/api/**/*.ts']`
-   - Bad: `paths: ['**/*.ts']` (too broad, wastes context)
+2. **Paths must be specific** — use `paths: ['src/api/**/*.ts']` rather than `'**/*.ts'` (too broad wastes context)
 
 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
+4. **Audit dates live in `.claude/codeyam-rule-state.json`** (managed by `codeyam memory touch`). Keep rule frontmatter limited to `paths`.
 
 ### Rule Template
 
@@ -337,7 +545,6 @@ Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
 ---
 paths:
   - 'specific/path/**/*.ts'
-timestamp: [CURRENT_ISO_TIMESTAMP]
 ---
 
 ## [Clear, Descriptive Title]
@@ -374,7 +581,7 @@ After generating rules based on your analysis and user answers:
 5. **Remind the user** to commit the new rules:
    ```
    git add .claude/rules/ .codeyam/rules/
-   git commit -m "Add rules for Claude Code (generated via /codeyam:memory)"
+   git commit -m "Add rules for Claude Code (generated via /codeyam-memory)"
    ```
 
 ---
@@ -394,11 +601,11 @@ After generating rules based on your analysis and user answers:
 The pre-commit hook **blocks commits** when:
 
 - Code files matching a rule's `paths` are modified
-- The rule's `timestamp` is older than the code changes
+- The rule's `lastAuditedAt` in `.claude/codeyam-rule-state.json` is older than the code changes
 
 To proceed:
 
 1. Review the flagged rule(s)
 2. Update content if needed
-3. Update the `timestamp` to current time
+3. Run `codeyam memory touch` to mark rules as audited in `.claude/codeyam-rule-state.json`
 4. Stage and commit

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')"