# unreflected-logs

## Purpose

Scan project directories for session logs that have not yet been processed by `/reflect-logs`, showing a per-project summary.

## Usage

```
unreflected-logs [OPTIONS] [DIRECTORY]
```

### Arguments

| Argument | Default | Description |
|----------|---------|-------------|
| `DIRECTORY` | `.` (current directory) | Root directory to scan |

### Flags

| Flag | Short | Description |
|------|-------|-------------|
| `--dryrun` | `-n` | List discovered projects without checking log status |
| `--help` | `-h` | Show usage information |

## Behaviour

1. **Discovery phase:** Walk `DIRECTORY` recursively, looking for directories that contain a `memory/log/` subdirectory. Each such directory is a "project". Stop descending into `memory/` and `node_modules/` directories.

2. **Check phase:** For each discovered project:
   a. List all `*.md` files in `memory/log/`.
   b. Read `.reflection-state.json` from the project root (sibling to `memory/`). If it doesn't exist, all logs are unreflected.
   c. A log file is "reflected" if its path (relative, as `log/<filename>`) appears as a key in the `processed` object of the reflection state file.
   d. Count reflected and unreflected logs.

3. **Report phase:** Print a summary:
   - **Projects with unreflected logs** get a section showing:
     - Project path (relative to `DIRECTORY`)
     - Count: `N unreflected / M total logs`
     - List of unreflected log filenames
   - **Projects with all logs reflected** are listed in a summary line (count only).
   - **Total** line at the end: `N unreflected logs across M projects`

4. **Exit code:**
   - `0` — no unreflected logs found anywhere
   - `1` — at least one unreflected log exists

## Dryrun Behaviour

When `--dryrun` is passed:
- Perform the discovery phase only
- Print each discovered project path (relative to `DIRECTORY`), one per line
- Prefix output with `[dryrun] Would check N projects:`
- Exit code is always `0`

## Edge Cases

| Scenario | Handling |
|----------|----------|
| No projects with `memory/log/` found | Print "No projects with session logs found in <dir>" and exit 0 |
| `memory/log/` exists but is empty | Skip project (no logs to report) |
| `.reflection-state.json` missing | Treat all logs as unreflected |
| `.reflection-state.json` malformed | Warn to stderr, treat all logs as unreflected |
| `processed` key missing from state | Treat all logs as unreflected |
| Permission denied on subdirectory | Skip with warning to stderr, continue scanning |

## Examples

### All reflected
```
Scanned 4 projects in ~/dev/claude

✓ All logs reflected across 4 projects.
```

### Some unreflected
```
Scanned 4 projects in ~/dev/claude

── projects/claude-foundations ──
   1 unreflected / 4 total logs
   - 2026-03-15.225345.md

── small-scripts ──
   2 unreflected / 3 total logs
   - 2026-03-14.091200.md
   - 2026-03-15.142300.md

✓ 2 projects have all logs reflected.

Total: 3 unreflected logs across 2 projects
```

### Dryrun
```
[dryrun] Would check 4 projects:
  ~/dev/claude/projects/claude-foundations
  ~/dev/claude/projects/cluster-bootstrap
  ~/dev/claude/small-scripts
  ~/dev/claude/octopus/customer-issue-sync
```