feat: v5 evolution layer — EVOLUTION.md, research/, decisions/ — closes #2

AGENTS.md

@@ -10,10 +10,11 @@ If an agent starts in this repository, it must orient by these files, not by hid
 2. `ARCHITECTURE.md`
 3. `OPERATIONS.md`
 4. `PRINCIPLES.md`
-5. `STATE.md` if it exists; otherwise create it from `STATE.template.md`
-6. `targets/README.md` if work touches an external repository
-7. the active `targets/<name>.local.md` target-pack if selected
-8. the concrete `tasks/TASK-XXX.md` task file if assigned
+5. `EVOLUTION.md`
+6. `STATE.md` if it exists; otherwise create it from `STATE.template.md`
+7. `targets/README.md` if work touches an external repository
+8. the active `targets/<name>.local.md` target-pack if selected
+9. the concrete `tasks/TASK-XXX.md` task file if assigned
 
 ## Roles
 

EVOLUTION.md

@@ -0,0 +1,82 @@
+# EVOLUTION — Framework Evolution Protocol
+
+## Purpose
+
+This document defines how `multiagentsystem` adopts external ideas, research findings, and design patterns into its canonical layer.
+
+Without a formal evolution mechanism, good ideas either disappear into chat history or enter canon without review. This protocol ensures every meaningful external input leaves a traceable artifact.
+
+## Read-Order Position
+
+Required reading for all agents. Position in read-order: after `PRINCIPLES.md`, before `OPERATIONS.md`.
+
+An agent that does not know the evolution mechanism will either propose changes chaotically or ignore valuable external ideas.
+
+## The Four Stages
+
+### 1. Intake
+
+External ideas enter via:
+- GitHub Issues with label `type:proposal`
+- `research/` folder for source-level reviews
+- GitHub Discussions (informal only --- no canonical decisions here)
+
+Rule: an idea without a GitHub artifact does not exist in the system.
+
+### 2. Research
+
+For any non-trivial idea:
+1. Create a source review file in `research/` using `SOURCE_REVIEW_TEMPLATE.md`
+2. Document: source, what it proposes, what fits our model, what conflicts, risk assessment
+3. Reference the review from the intake issue
+
+### 3. Decision
+
+Accepted or rejected ideas become decisions:
+1. Create a decision file in `decisions/` using `DECISION_TEMPLATE.md`
+2. Status: `accepted` or `rejected`
+3. Link to source review and intake issue
+4. For `accepted`: add implementation tasks
+
+Rule: no external feature enters canon without a decision artifact.
+
+### 4. Promotion
+
+Accepted decisions are promoted into canon via Pull Requests:
+- PR must reference the decision file
+- PR must reference the source review
+- PR must update affected canonical docs (AGENTS.md, OPERATIONS.md, etc.)
+- PR must not introduce machine-local paths or product-specific references
+
+## What Goes Into `research/`
+
+Source reviews for:
+- external repositories with patterns we might adopt
+- articles, papers, or posts that propose architectural approaches
+- internal experiments that should be documented before adoption
+
+Format: see `research/SOURCE_REVIEW_TEMPLATE.md`.
+
+## What Goes Into `decisions/`
+
+One file per design decision. Both accepted and rejected decisions are recorded.
+
+Rejected decisions are equally important --- they prevent re-litigating the same ground.
+
+Format: see `decisions/DECISION_TEMPLATE.md`.
+
+## Evolution vs Dispute
+
+Evolution: adopting or rejecting an external pattern.
+Dispute: disagreement between agents or roles about an internal framework rule.
+
+Use `type:dispute` issues for disputes. Use `type:proposal` issues for evolution intake.
+
+## Canon Stability Rule
+
+During v5 evolution, existing canon is stable unless:
+1. A decision artifact explicitly changes it
+2. The change is implemented via PR with review
+3. Affected docs are updated in the same PR
+
+Do not patch canon docs in side PRs without a linked decision.

decisions/DECISION_TEMPLATE.md

@@ -0,0 +1,49 @@
+# DECISION-NNN: Short Title
+
+## Status
+
+`accepted` / `rejected` / `deferred`
+
+## Date
+
+YYYY-MM-DD
+
+## Context
+
+*(What problem or opportunity prompted this decision)*
+
+## Options considered
+
+### Option A
+
+*(Description)*
+
+Pros:
+-
+
+Cons:
+-
+
+### Option B
+
+*(Description)*
+
+Pros:
+-
+
+Cons:
+-
+
+## Decision
+
+*(What was decided and why)*
+
+## Consequences
+
+*(What changes as a result --- canonical docs, scripts, templates)*
+
+## Related
+
+- Source review: *(link to research/SOURCE-NNN.md if applicable)*
+- Proposal issue: *(link)*
+- Implementation PR: *(link when available)*

decisions/README.md

@@ -0,0 +1,19 @@
+# decisions/
+
+One file per design decision. Both accepted and rejected decisions are recorded here.
+
+## Naming
+
+`DECISION-NNN-short-title.md` (e.g. `DECISION-001-worktree-isolation-scope.md`)
+
+## Status values
+
+- `accepted` --- adopted into canon or implementation planned
+- `rejected` --- explicitly not adopted, with rationale recorded
+- `deferred` --- valid idea, not prioritized now, revisit condition noted
+
+## Index
+
+| Decision | Status | Summary |
+|----------|--------|---------|
+| *(none yet --- first decisions pending)* | | |

research/README.md

@@ -0,0 +1,23 @@
+# research/
+
+Source reviews for external repositories, articles, and patterns considered for adoption into `multiagentsystem`.
+
+## When to create a review
+
+Create a source review when:
+- you encounter an external repository with patterns worth evaluating
+- a proposal issue references an external source
+- you want to formally document why an external idea was rejected
+
+## How to create a review
+
+1. Copy `SOURCE_REVIEW_TEMPLATE.md`
+2. Name it `SOURCE-NNN-short-name.md` (e.g. `SOURCE-001-oh-my-claudecode.md`)
+3. Fill in all sections
+4. Reference it from the related proposal issue
+
+## Completed reviews
+
+| File | Source | Decision |
+|------|--------|----------|
+| *(none yet --- first reviews pending)* | | |

research/SOURCE_REVIEW_TEMPLATE.md

@@ -0,0 +1,42 @@
+# SOURCE-NNN: Short Name
+
+## Source
+
+- Repository / URL:
+- Author:
+- License:
+- Reviewed on:
+- Reviewed by:
+
+## What it proposes
+
+*(2--4 sentences describing the core idea)*
+
+## What fits our model
+
+*(List of ideas that are compatible with multiagentsystem principles)*
+
+- 
+
+## What conflicts
+
+*(List of ideas that conflict, with reason)*
+
+- 
+
+## Risk assessment
+
+- Breaking changes to existing canon: yes / no
+- Complexity: low / medium / high
+- License compatibility: yes / no / unknown
+
+## Recommendation
+
+`adopt` / `adapt` / `reject` / `defer`
+
+*(One paragraph rationale)*
+
+## Related
+
+- Proposal issue:
+- Decision file: *(fill after decision is made)*