# Evolution Playbook

This skill now has a bounded self-improvement loop.

The goal is not uncontrolled self-modification. The goal is to make `fofamap` learn from real runs so the next query, report, and handoff are better.

## What It Learns Automatically

After `search`, `search-next`, `host`, `stats`, `project-run`, and `monitor-run`, the helper records:

- what mode ran
- whether it succeeded or failed
- which report profile was used
- whether FOFA dropped requested fields
- whether zero-result broadening lessons appeared
- whether alive-check showed stale inventory
- whether high-signal ports, abnormal exposure markers, attack-infrastructure hints, or takeover hints appeared
- what next-action guidance should be preserved

## Memory Layout

By default, local memory is written to:

`results/fofamap_memory/`

Important files:

- `runs.jsonl`: append-only episodic memory
- `semantic-patterns.json`: aggregated pattern counts and recurring lessons
- `latest_reflection.json`: last run's structured reflection
- `latest_reflection.md`: last run's human-readable reflection
- `latest_review.md`: latest explicit review generated by `learn-review`

Optional environment variables:

- `FOFAMAP_MEMORY_DIR`: override the memory directory
- `FOFAMAP_DISABLE_LEARNING=1`: disable the learning loop

## Self-Repair

The skill self-repairs operationally by:

- recording failed runs instead of discarding them
- turning repeated failures into stable lessons
- remembering tier-related field drops
- warning when a query strategy is too brittle
- reminding the next operator to broaden by signal family instead of repeating the same dead query

This is operational self-repair, not silent code mutation.

## Self-Reflection

Run:

```bash
python3 scripts/fofa_recon.py learn-review
```

Or write the review to a file:

```bash
python3 scripts/fofa_recon.py learn-review --output evolution_review.md
```

The review summarizes:

- strongest learned patterns
- recurrent friction
- frequently rejected FOFA fields
- report profile usage
- recent episodes
- guidance for the next operator

## Self-Evolution

Each successful or failed run updates the semantic memory. That means the skill gradually accumulates:

- which lenses produce better reports
- which failure patterns happen repeatedly
- which FOFA constraints most often bite the workflow
- which exposure classes recur in the current environment

The helper also returns `learning_artifacts` with `evolution_hints`, so the host agent can adapt its next step immediately.

## How The Host Agent Should Use This

When the task is recurring, long-running, or team-oriented:

1. read `latest_reflection.md` if it exists
2. inspect `semantic-patterns.json` when you need a stronger sense of recurring lessons
3. prefer the report profile that matches the strongest recurring mission
4. keep separating indexed evidence from live validation

## Guardrails

- Learning is local to the current workspace unless the user redirects the memory directory.
- The loop improves query planning, field choices, report quality, and operator guidance.
- It does not autonomously rewrite the skill package.
- If the user wants actual code evolution, treat `learn-review` as the evidence base and patch the skill explicitly.