lore-evolve

name	lore-evolve
description	Compile knowledge increments into project snapshot with conflict detection
category	ai-context

/evolve — Snapshot Compilation

When to Trigger

• User explicitly invokes this skill
• Stop hook detects 10+ rounds of accumulated knowledge (hard limit)
• Periodic maintenance (agent notices many uncompiled increments)
• After a major feature completion or PR merge

Purpose

Compile all accumulated increment files into a single, coherent .ai-context/snapshot.md — the agent's "long-term memory" of the project. This is the project's living architecture document that grows more accurate with each compilation.

Process

Step 0: Detect Modular Mode

Check if .ai-context/modules/ directory exists.

• If no → Check if this is the first compile with sufficient module-scoped knowledge. If snapshot.md has knowledge entries with file references that can be mapped to code directories, auto-trigger modular partitioning by executing /lore-modularize before proceeding. Then run legacy evolve if no modules were discovered.
• If yes → Run modular evolve path (Steps 1-8 below).

Step 1: Read Current State

Read:

1. .ai-context/snapshot.md — current snapshot (may not exist for first compile)
2. .ai-context/modules/_index.md — module registry (if modular mode)
3. For each known module, read modules/<name>/knowledge.md
4. All files in .ai-context/increments/ — sorted by date (oldest first)
5. For each module, read modules/<name>/increments/
6. .ai-context/config.yaml — project configuration

Step 2: Route Increments by Domain

For each uncompiled increment (global or per-module):

Determine target:

• Has domain: <module-name> meta field AND module exists in _index.md → target that module's knowledge.md
• No domain field but affected_files paths match a module's code path → infer domain, target that module
• No domain and no file path match → target global snapshot.md
• domain references unknown module → create warning, route to global snapshot.md

Step 3: Conflict Detection (per-target)

For each new increment, check against its target (snapshot.md or modules//knowledge.md):

Conflict scenarios:

• A DECISION contradicts an existing decision (e.g., different values for the same config)
• A CONSTRAINT contradicts an existing constraint
• An ARCHITECTURE description conflicts with existing understanding

Conflict handling:

### [CONFLICT] Payment timeout threshold
- Snapshot says: 3000ms (recorded 2026-04-01, author: 张三, status: verified)
- New increment says: 5000ms (recorded 2026-04-23, author: 利普, status: unverified)
- 状态: pending_resolution
- 处理: 需要人工裁决。在确认前，快照保留双方记录。

Rules:

• Do NOT auto-resolve conflicts
• Preserve both the old and new entries
• Mark as [CONFLICT] pending_resolution
• Cross-module conflicts → flagged in both modules + _index.md

Step 4: Merge Knowledge (per-target)

For non-conflicting new increments, merge into the target. For each section:

Project Overview

• If new increment changes project description (new module, new capability) → update
• Usually stable after init

Architecture

• Flows: Add new flows from increments, update existing ones if modified
• Modules: Add/remove modules as needed
• State Machines: Update if state machine changes detected

Key Decisions

• Add: New decisions from increments that don't exist
• Update: Existing decisions that have been superseded → mark old as "Superseded: YYYY-MM-DD by author — reason"
• Remove: Never remove — always keep as historical record

Constraints

• Add: New constraints from increments
• Update: Existing constraints with new information
• Remove: Never remove — mark as "Resolved: YYYY-MM-DD" if no longer applicable

External Dependencies

• Add: New external types, APIs, DTOs discovered
• Update: Field descriptions if new information available

Config Index

• Add: New configuration entries
• Update: If configuration location or meaning changed

Business Context

• Add: New business scenarios, relationships
• Update: Existing descriptions with new details

Glossary

• Add: New terms from increments
• Update: Definitions if clarified

Step 5: Confidence Filtering

When compiling snapshot:

• high confidence → directly included in snapshot
• medium confidence → included but marked [待验证]
• low confidence → NOT included in snapshot, but noted in a "Pending Verification" section at the end

## Pending Verification (low confidence knowledge, needs confirmation)
- [EXTERNAL] AbilityExpand 有 3 个字段 — 来源: agent 推断, 需验证

Step 6: Write Outputs

Write .ai-context/snapshot.md (global knowledge):

# AI Context Snapshot

> Auto-generated by /evolve. Do not edit manually.
> Last compiled: YYYY-MM-DD
> Compiled increments: 2026-04-23_payment-timeout-adjust, 2026-04-25_add-scene-image, ...

[All merged sections follow]

## Conflict Log
- [CONFLICT] Payment timeout: pending_resolution (see Key Decisions)

Write modules/<name>/knowledge.md for each affected module using templates/module-knowledge.md.

Write updated modules/_index.md if new modules were discovered or cross-refs changed.

Size constraint: Keep each knowledge file under 200 lines. If it grows beyond:

• Archive historical decisions to modules/<name>/archive/decisions-history.md
• Keep only current, actionable knowledge in knowledge.md
• Preserve the full history in archive — never lose knowledge, just move it

Step 7: Archive Old Increments

Move all compiled increments to archive:

# Global increments
mv .ai-context/increments/*.md .ai-context/increments/archive/ 2>/dev/null || true

# Per-module increments
for module_dir in .ai-context/modules/*/; do
  mv "$module_dir/increments"/*.md "$module_dir/increments/archive/" 2>/dev/null || true
done

Step 8: Update Module Registry

If /lore-evolve discovered new modules during routing (from affected_files paths), add them to _index.md.

Step 9: Git Add

git add .ai-context/snapshot.md
git add .ai-context/increments/archive/
git add .ai-context/modules/

Output

Report to user:

Snapshot compiled:
- Mode: modular (X modules) | legacy (single-file)
- Updated sections: Architecture, Key Decisions, Constraints
- New knowledge: +2 decisions, +1 constraint
- Module changes: order +1 decision, payment +1 constraint
- Conflicts: 1 pending_resolution (Payment timeout)
- Low confidence: 1 item pending verification
- Archived: 3 global increments, 2 module increments
- Snapshot size: 145 lines (global), 98 (order), 67 (payment)