# Evolution Rules

## Purpose

These rules allow the AI development team files to evolve safely.

## Main Rule

Agents may propose changes. The Product Owner approves changes.

## Ownership Layers

### Upstream-managed reusable system

These files can be promoted back into the shared boilerplate repository:

- `./.ai/AGENTS.md`
- `./.ai/SKILLS.md`
- `./.ai/version.md`
- `./.ai/agents/`
- `./.ai/skills/`
- `./.ai/workflows/`
- `./.ai/templates/`
- `./.ai/checklists/`
- `./.ai/evolution/`
- `./CLAUDE.md`
- `./AGENTS.MD`

### Project-owned state

These files belong to the downstream project and should not be promoted unless the learning clearly generalizes:

- `./.ai/project/`

### Local-only state

These files are transient and are not part of the upstream baseline:

- `./.ai/logs/`
- `./.ai/local/`

## Proposal Scopes

Every improvement proposal must declare one scope:

- `local-only` for personal notes, scratch work, or temporary experiments
- `project-only` for downstream project conventions or facts
- `upstream-candidate` for reusable rules that should be considered for this boilerplate repo

## What Can Evolve

- Agent role files
- Skill files
- Workflow files
- Templates
- Checklists
- Project decision files

## What Should Not Be Changed Casually

- Product Owner authority
- Security rules
- Definition of Done
- Approval requirements
- Folder structure
- Project vision

## Approved Update Process

1. Identify a durable lesson.
2. Decide whether it is `local-only`, `project-only`, or `upstream-candidate`.
3. Create an improvement proposal in `./.ai/evolution/proposals/`.
4. State the exact file and section to change.
5. Explain benefit, risk, and why the lesson generalizes if upstream promotion is requested.
6. Wait for Product Owner approval.
7. Apply the change to the correct ownership layer.
8. Add a learning-log entry for durable approved changes.
9. Update `./.ai/version.md` when the reusable baseline changes.

## Upstream Promotion Workflow

Use this flow when a downstream project discovers something that should improve the boilerplate:

1. Capture the lesson in a proposal marked `upstream-candidate`.
2. Reference the source project and evidence.
3. Separate project-specific facts from reusable operating guidance.
4. Approve the proposal with the Product Owner.
5. Apply the reusable change in the upstream-managed layer.
6. Bump the baseline version in `./.ai/version.md`.
7. Merge the change into the shared remote repository.
8. Pull or merge the new baseline into downstream projects.

## Conflict Resolution

When files conflict, priority order is:

1. Product Owner instruction
2. Current task instruction
3. `AGENTS.md`
4. `SKILLS.md`
5. Agent file
6. Skill file
7. Workflow file
8. Template file
9. Historical learning log