# Codebase Genome Pipeline

Issue: `timmy-home#665`

This pipeline gives Timmy a repeatable way to generate a deterministic `GENOME.md` for any repository and rotate through the org nightly.

## What landed

- `pipelines/codebase_genome.py` — static analyzer that writes `GENOME.md`
- `pipelines/codebase-genome.py` — thin CLI wrapper matching the expected pipeline-style entrypoint
- `scripts/codebase_genome_nightly.py` — org-aware nightly runner that selects the next repo, updates a local checkout, and writes the genome artifact
- `GENOME.md` — generated analysis for `timmy-home` itself

## Genome output

Each generated `GENOME.md` includes:

- project overview and repository size metrics
- Mermaid architecture diagram
- entry points and API surface
- data flow summary
- key abstractions from Python source
- test coverage gaps
- security audit findings
- dead code candidates
- performance bottleneck analysis

## Single-repo usage

```bash
python3 pipelines/codebase_genome.py \
  --repo-root /path/to/repo \
  --repo-name Timmy_Foundation/some-repo \
  --output /path/to/repo/GENOME.md
```

The hyphenated wrapper also works:

```bash
python3 pipelines/codebase-genome.py --repo-root /path/to/repo --repo Timmy_Foundation/some-repo
```

## Nightly org rotation

Dry-run the next selection:

```bash
python3 scripts/codebase_genome_nightly.py --dry-run
```

Run one real pass:

```bash
python3 scripts/codebase_genome_nightly.py \
  --org Timmy_Foundation \
  --workspace-root ~/timmy-foundation-repos \
  --output-root ~/.timmy/codebase-genomes \
  --state-path ~/.timmy/codebase_genome_state.json
```

Behavior:

1. fetches the current repo list from Gitea
2. selects the next repo after the last recorded run
3. clones or fast-forwards the local checkout
4. writes `GENOME.md` into the configured output tree
5. updates the rotation state file

## Example cron entry

```cron
30 2 * * * cd ~/timmy-home && /usr/bin/env python3 scripts/codebase_genome_nightly.py --org Timmy_Foundation --workspace-root ~/timmy-foundation-repos --output-root ~/.timmy/codebase-genomes --state-path ~/.timmy/codebase_genome_state.json >> ~/.timmy/logs/codebase_genome_nightly.log 2>&1
```

## Limits and follow-ons

- the generator is deterministic and static; it does not hallucinate architecture, but it also does not replace a full human review pass
- nightly rotation handles genome generation; auto-generated test expansion remains a separate follow-on lane
- large repos may still need a second-pass human edit after the initial genome artifact lands