@codeyam/codeyam-cli 0.1.0-staging.d3e886e → 0.1.0-staging.d57a578

package/codeyam-cli/templates/skills/codeyam-dev-mode/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: codeyam-dev-mode
+autoApprove: true
+description: |
+  Use this skill when working in CodeYam Dev Mode — an interactive environment for iterating on
+  components and scenarios with a live preview panel alongside a Claude Code terminal.
+  Use when: The embedded terminal in Dev Mode auto-invokes this skill to provide entity/scenario context.
+---
+
+# CodeYam Dev Mode
+
+You are working inside CodeYam Dev Mode — a split-screen environment with this Claude Code terminal on the left and a live preview on the right.
+
+## Step 1: Read Session Context
+
+Read the dev mode context file to understand the current entity and scenario:
+
+```
+cat .codeyam/dev-mode-context.md
+```
+
+The context file contains all the specific paths you need — source file, mock data, dev server project, and **server log**. All paths are fully resolved; no placeholders to fill in.
+
+## Step 2: Gather Context While Server Sets Up
+
+The dev server needs time to set up the sandboxed project (copying files, installing deps, starting Vite). The mock data files in the tmp project **do not exist yet** when you first start. Use this time productively.
+
+**Do these in parallel:**
+
+1. **Read the source file** from the real repo (exists immediately).
+
+2. **Query the database** for all scenarios belonging to this entity's analysis. Use the **Analysis ID** from the context file:
+
+   ```
+   sqlite3 .codeyam/db.sqlite3 "SELECT name, description FROM scenarios WHERE analysis_id = '<ANALYSIS_ID>'"
+   ```
+
+   Each scenario's `description` explains what data shape it tests — e.g. "empty list", "many items", "error state". This tells you what data attributes matter most for the component's visual states.
+
+3. **Monitor the server log** listed in the context file under **Server log**:
+
+   ```
+   tail -f <server log path from context file>
+   ```
+
+   Wait until you see a local URL like `http://localhost:...` indicating the Vite server has started. Do NOT try to read mock data or other files from the tmp project until the logs confirm setup is complete.
+
+## Step 3: Read Mock Data and Present Overview
+
+Once the dev server is ready, read the **mock data file** from the tmp project path listed in the context file.
+
+Then present a **concise** overview to the user:
+
+1. **Component Summary** — 2-3 sentences on what the component does and the current scenario being previewed.
+
+2. **Suggested Tests** — Compare the component's code paths (conditionals, edge cases, visual states) against the existing scenarios from the database. Recommend 2-4 specific ways to test the component that are **not yet covered** by saved scenarios. Focus on interesting visual states — e.g. "What does this look like with a very long title?", "What happens when the list is empty?", "How does the error state render?". Also suggest ways to enrich the _existing_ scenario's data to better exercise the component (more realistic content, populated optional fields, diverse values). Be specific to this component, not generic.
+
+Keep it brief — no tables, no exhaustive attribute lists. The user can see the preview and wants actionable suggestions, not a data dump.
+
+## How Dev Mode Works
+
+**Layout:**
+
+- **Left panel** — This Claude Code terminal (you)
+- **Right panel** — Live preview iframe showing the rendered component/scenario
+
+**Architecture:**
+
+- The preview runs from a sandboxed project at the tmp path listed in the context file
+- Source code edits in the real repo auto-sync to the preview via HMR (hot module replacement)
+- Mock data files live in the tmp project under `__codeyamMocks__/`
+
+**What you can edit:**
+
+- **Source code** (the entity's file in the real repo) — edits sync automatically to the preview
+- **Mock data** (the `MockData_*.tsx` file in the tmp project) — edits also sync via HMR
+- Both types of edits show up in the preview almost instantly
+
+**CRITICAL — What you must NEVER edit for functional changes:**
+
+- **Shimmed component files** (`*_Scenario.tsx` in the tmp project) — these are auto-generated files that wire up the component with mocked dependencies. **NEVER modify these to change what renders.** Any functional changes you make here:
+  - Will be lost when the scenario is recaptured or regenerated
+  - Cannot be saved as a scenario (only mock data is persisted to the database)
+  - Break the ability to reproduce the scenario in the future
+- To change what the component displays, **always edit the `MockData_*.tsx` file**. The shimmed component reads mock data via `scenarios().data()` — that's the mechanism for controlling component behavior and visual state.
+- The ONLY acceptable edit to a shimmed component file is adding temporary `console.log` statements for debugging (see Client-Side Logging below). Never change imports, state initialization, hooks, memos, or rendering logic.
+
+## Workflow
+
+1. Read the context file (`.codeyam/dev-mode-context.md`)
+2. While dev server sets up, do in parallel:
+   - Read the source file (from real repo — available immediately)
+   - Query database for scenario names/descriptions (available immediately)
+   - Monitor server log until dev server is ready
+3. Read the mock data file (from tmp project — only after setup completes)
+4. Present concise overview: component summary + suggested untested scenarios
+5. Ask the user what they want to change
+6. Make incremental edits to **source code or mock data only** — the preview updates live
+7. After making changes, refresh the preview (curl command from context file)
+8. Iterate based on user feedback
+
+## Client-Side Logging (Required)
+
+**Always add `console.log` statements to trace the execution flow when making changes.** This is critical — you cannot see the preview, so logging is your only way to verify the component renders as expected.
+
+Client-side `console.log` and `console.error` calls are automatically captured by the `/api/client-log` endpoint and written to the server log file. This means you can add logging in component code and read it from the server log.
+
+**When to add logging:**
+
+- Before and after every change you make to the shimmed component or mock data
+- At key data flow checkpoints: after state initialization, after useMemo computations, before the render return
+- In useEffect callbacks to confirm they fire
+- Around conditional branches you're targeting (e.g. "this condition should now be true")
+
+**How to log:**
+
+Add `console.log` with a `[CY-DEBUG]` prefix in the shimmed component file (the `*_Default_Scenario.tsx` file in the tmp project). **This is the ONLY acceptable edit to shimmed component files — temporary debug logging. Never change the component's logic, imports, state, or rendering in these files.**
+
+```typescript
+// After state declarations:
+console.log(
+  '[CY-DEBUG] render: myState:',
+  myState?.length,
+  'otherData:',
+  otherData,
+);
+
+// Inside useEffect:
+useEffect(() => {
+  console.log('[CY-DEBUG] useEffect fired, setting data');
+  // ...
+}, []);
+
+// Before return:
+console.log(
+  '[CY-DEBUG] PRE-RENDER: showThumbnails:',
+  items?.length > 0,
+  'showLoader:',
+  !items,
+);
+```
+
+**After refreshing, always check the log** for your `[CY-DEBUG]` lines:
+
+```
+tail -30 <server log path from context file>
+```
+
+If you don't see your debug logs but see `[CLIENT CONSOLE.ERROR]` or `Application Error`, the component is crashing before your code runs. Read the error stack trace to find the failing component.
+
+**Keep logging in place** as you iterate — it costs nothing and saves significant debugging time.
+
+## Refreshing the Preview
+
+After making changes, refresh the live preview so it picks up your edits. The exact curl command is in the context file under **Server > Refresh preview** — copy and run it:
+
+```
+curl -s -X POST http://localhost:<port>/api/dev-mode-preview
+```
+
+**Always refresh after making changes.** This triggers the preview iframe to reload, **clears the server log file**, waits for the page to re-render, and then fetches the preview URL to check for SSR errors.
+
+**The response includes preview health info.** Check the `preview` field in the JSON response:
+
+```json
+{
+  "success": true,
+  "sessionsNotified": 1,
+  "logCleared": true,
+  "preview": {
+    "status": 200,
+    "healthy": true
+  }
+}
+```
+
+If the preview is unhealthy (e.g., SSR error caught by an error boundary), the response will include the error:
+
+```json
+{
+  "preview": {
+    "status": 500,
+    "healthy": false,
+    "error": "ReferenceError: myVariable is not defined\n    at Component (/path/to/file.tsx:42:5)"
+  }
+}
+```
+
+**After every refresh:**
+
+1. **Check `preview.healthy`** in the JSON response. If `false`, the `error` field contains the SSR error — fix it before proceeding.
+2. **Check the log** for your `[CY-DEBUG]` lines to confirm the execution path:
+
+```
+tail -30 <server log path from context file>
+```
+
+If the preview was unhealthy, the log will also contain `[DEV-MODE-CHECK]` lines with the error details.
+
+Look for your `[CY-DEBUG]` lines to confirm the execution path. If you see errors instead, the component is crashing. If you see nothing, the page may still be loading — wait a moment and check again.
+
+## Debugging with Server Logs
+
+The **Server log** path in the context file captures all output from the dev server process — Vite compilation errors, SSR errors, HMR updates, and runtime warnings. **Client-side errors** (React rendering errors, unhandled exceptions, console.error calls) are also automatically reported to this log via the `/api/client-log` endpoint. This means both server and client errors appear in the same log file.
+
+Since the log is **cleared on every refresh**, you always see fresh output. No need to scroll past old errors.
+
+**When to check the server log:**
+
+- **After every refresh** — always verify your debug logs appear and no errors are present
+- The preview shows a blank page, error boundary, or 500 error
+- HMR updates aren't taking effect after edits
+- The preview is stuck loading or shows unexpected content
+
+**How to check:**
+
+```
+tail -50 <server log path from context file>
+```
+
+**What to look for:**
+
+- `[CY-DEBUG]` — your trace logs confirming the execution path and data values
+- `[CLIENT CONSOLE.ERROR]` — client-side React errors or unhandled exceptions
+- `[vite]` error messages — TypeScript compilation failures
+- `Application Error` — React error boundary activated (component crashed during render)
+- No output at all — the page hasn't loaded yet, or the component never rendered
+
+## Tips
+
+- **NEVER modify shimmed component files** (`*_Scenario.tsx`) to change rendering behavior — only edit `MockData_*.tsx` files to change what the component displays. Shimmed components are auto-generated; functional changes to them won't persist and can't be saved as scenarios.
+- **Refresh the preview frequently** — the user is watching the preview panel as you work. Make small changes, then refresh so they see visual progress. Don't batch multiple edits into one big refresh at the end. Aim for a refresh after every meaningful edit (new data values, layout changes, style tweaks).
+- **Always add `[CY-DEBUG]` logging before refreshing** — never refresh without a way to verify the result
+- Mock data files are TypeScript (`.tsx`) — they export scenario-specific props/data
+- The database at `.codeyam/db.sqlite3` has entity and scenario metadata if you need deeper investigation
+- If the preview breaks, check the server log (path in context file) for compilation or runtime errors
+- You can also modify other files in the repo that the entity imports — those changes sync too

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

@@ -0,0 +1,149 @@
+---
+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 steps`.
+
+**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 13 gated steps:
+
+```
+codeyam editor steps → 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   → Verify screenshots and audit
+codeyam editor 13   → Present summary, get final approval
+```
+
+**You MUST run each command and follow its checklist before moving to the next.** Steps 1, 3, and 13 require user confirmation. After step 13, loop back to step 1.
+
+## Handling User Feedback / Changes
+
+When the user asks for changes — whether through the menu, a direct request, or even a question that implies a change (e.g., "Can the cards have images?") — you MUST run `codeyam editor change` **before** making any modifications. This includes:
+
+- Code changes (components, routes, lib functions, styles)
+- Scenario data updates (seed data, localStorage data, mock data)
+- Style adjustments (CSS, Tailwind classes, layout tweaks)
+- Even small fixes (typos, color tweaks, spacing)
+
+This command gives you the post-change checklist (re-register scenarios, re-run tests, update journal, etc.). Never make changes without running the change workflow first.
+
+**CRITICAL:** The change workflow MUST end with `codeyam editor 13`, which shows Working Session Results to the user. Skipping this step is a broken experience — the user will not see what changed and cannot approve or request further changes. Every change, no matter how small, must conclude with results being shown.
+
+## 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
+- **Keep the preview moving** — the user watches the preview panel as you work. Refresh it frequently so they see progress, not a static screen. See below.
+
+## Keep the Preview Moving
+
+The user is watching the live preview panel while you work. A static preview makes it feel like nothing is happening. **Refresh the preview after every meaningful change** — not just at the end of a step.
+
+**During prototyping (step 2):**
+
+- Refresh after creating the first visible page, even if it's bare
+- Refresh after adding each major UI section (header, list, form, etc.)
+- Refresh after seeding data so the user sees real content appear
+- Refresh after styling changes so the user sees the visual progress
+
+**During extraction (step 5):**
+
+- Refresh after extracting each batch of components to confirm nothing broke
+
+**During changes:**
+
+- Refresh after each individual change, not after all changes are done
+
+**How to refresh:**
+
+```
+codeyam editor preview '{"dimension":"<name from screenSizes>"}'
+```
+
+Navigate to a specific path or switch scenario:
+
+```
+codeyam editor preview '{"path":"/drinks/1","dimension":"<name from screenSizes>"}'
+codeyam editor preview '{"scenarioId":"abc-123"}'
+```
+
+The goal: the user should see the preview update 4-8+ times during a typical building session, not just once at the end.
+
+## Collaboration
+
+Isolation routes are committed to git (not gitignored). They are protected by a layout guard at `app/isolated-components/layout.tsx` that returns `notFound()` in production, so they are safe to commit. Scenarios, screenshots, journal entries, and the glossary are also committed. Only the local database and secrets are gitignored.
+
+When a collaborator clones the repo and runs `codeyam editor`, scenarios are auto-imported from `scenarios-manifest.json`. Run `codeyam editor sync` to manually re-sync after pulling new changes.
+
+## Quick Reference
+
+```bash
+# Register component scenario (auto-captures screenshot)
+# ALWAYS include "dimensions" — use the project's default screen size name from setup
+codeyam editor register '{"name":"DrinkCard - Default","componentName":"DrinkCard","componentPath":"app/components/DrinkCard.tsx","url":"/isolated-components/DrinkCard?s=Default","dimensions":["<name from screenSizes>"],"mockData":{"routes":{"/api/...":{"body":[...]}}}}'
+
+# Register app scenario with seed data (ALWAYS include "url" and "dimensions")
+codeyam editor register '{"name":"Full Catalog","type":"application","url":"/","dimensions":["<name from screenSizes>"],"seed":{"drinks":[...]}}'
+
+# Register app scenario with localStorage (for apps using client-side storage instead of a database)
+codeyam editor register '{"name":"Full Library","type":"application","url":"/","dimensions":["<name from screenSizes>"],"localStorage":{"articles":[...],"collections":[...]}}'
+
+# For large seed/localStorage data, write JSON to a temp file and use @ prefix:
+codeyam editor register @/tmp/scenario-data.json
+
+# Journal entry (one per feature, references scenario names)
+codeyam editor journal '{"title":"...","type":"feature","description":"..."}'
+
+# Update journal with commit info
+codeyam editor journal-update '{"time":"...","commitSha":"...","commitMessage":"..."}'
+
+# Refresh preview / navigate / switch scenario (ALWAYS include "dimension")
+codeyam editor preview '{"dimension":"<name from screenSizes>"}'
+codeyam editor preview '{"path":"/drinks/1","dimension":"<name from screenSizes>"}'
+codeyam editor preview '{"scenarioId":"abc-123"}'
+
+# Show/hide results panel
+codeyam editor show-results
+codeyam editor hide-results
+
+# Commit feature
+codeyam editor commit '{"message":"feat: Add drinks page"}'
+
+# Restart dev server (only for config/dependency changes)
+codeyam editor dev-server '{"action":"restart"}'
+
+# Check for client-side errors
+codeyam editor client-errors
+
+# Verify all images load (extracts URLs from pages, HTTP-checks each one)
+codeyam editor verify-images '{"paths":["/","/drinks/1"]}'
+
+# Sync scenarios from manifest (after pulling collaborator changes)
+codeyam editor sync
+```

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

@@ -208,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
+node .claude/skills/codeyam-memory/scripts/holistic-analysis/detect-deprecated-patterns.mjs
+```
+
+```bash
+node .claude/skills/codeyam-memory/scripts/holistic-analysis/find-exports.mjs
+```
+
+```bash
+node .claude/skills/codeyam-memory/scripts/session-mining/preprocess.mjs 2>/dev/null
+```
+
+Capture the stdout of `preprocess.mjs` — each line is a path to a filtered session file.
+
+### Step 2: Extract sizing metrics
+
+Use quick one-liners to extract counts — do NOT read the full JSON files into the main context:
+
+```bash
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/deprecated-scan.json '.dependencies | length'
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/deprecated-scan.json '.explicit_markers | length'
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/exports-scan.json '.stats.total_exports'
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/exports-scan.json '.stats.total_files'
+```
+
+The session count is the number of lines from `preprocess.mjs` 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
@@ -282,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):