docs: keep superseded design-round doc history

Supporting documents folded into agentic-teams.md (the canonical unified
design record), retained as historical context:

- agentic-teams-review.md (round 2)
- vision-fidelity.md (round 3 diagnosis + research)
- epic-task-artifact-model.md (Epic/epictask/task + context philosophy)
- session-summary-vision-fidelity.md (session narrative)

All superseded by docs/agentic-teams.md, which remains the source of truth.

docs/epic-task-artifact-model.md

@@ -0,0 +1,156 @@
+# Epic / Task / EpicTask + Artifact Context Model
+
+> **Status:** Design discussion — capturing decisions from the conversation.
+> **Purpose:** Durably record the data model (Epic, epictask, task) and the
+> IPython-style artifact/context philosophy the user is designing. Builds on
+> `docs/agentic-teams.md` (round 1) + `docs/agentic-teams-review.md` (round 2).
+>
+> The through-line from round 2 — **async, artifact-driven, human-as-fuse** —
+> is preserved here. This doc adds the *vision layer* (the Epic) and the
+> *context-management layer* (artifacts + eviction priorities) that the earlier
+> rounds never defined.
+
+---
+
+## 1. The Epic — the vision, made a first-class thing
+
+An **Epic** is the agreed statement of what we want to achieve. It is the
+result of the back-and-forth **before coding starts**: the discussion *is* the
+vision, and the Epic captures its conclusion. It is project-scoped.
+
+### What an Epic holds
+- The **agreed "done" criteria** — the checkable outcomes plus the intent/quality
+  attributes that define 100% delivery. Written at vision time so "compare
+  delivered vs vision" has something authoritative to diff against.
+- Its **scope changes** over time (revisions), so creep/drift is visible too —
+  not just under-delivery.
+- **Tradeoff decisions** the user makes along the way.
+
+### When is an Epic "done"?
+An Epic is **done ONLY when one of two things is true**:
+1. **100% of the vision is delivered**, OR
+2. The **user explicitly accepted tradeoffs** — e.g. a known issue we couldn't
+   fix ("we accept this gap because"). The accepted-tradeoffs are recorded on
+   the Epic so the "done" is honest and auditable.
+
+### The Epic-comparison moment → the joint-debug trigger
+After agents report their work done, the delivered whole is **compared against
+the Epic**. Two classes of gap:
+
+- A **listed must-have isn't shipped** → reopen the under-delivering task, or
+  add a new task for the missing piece (see §3).
+- A quality/design gap or a **"we couldn't fix X"** situation → this is the
+  natural moment to **`exec`**: the user drops into the agent's workspace and
+  does a **joint debugging session** (the pi / Claude-Code live experience),
+  working the hard problem together rather than accepting a reduction or
+  filing more async work.
+
+So "deliver → compare → gap" routes not only to reopen/new-task, but also to
+**live collaboration** — giving `exec` a concrete, principled trigger point
+that round 2 noted was missing (LE-10 / LE-4 boundary).
+
+---
+
+## 2. The data model — project resources
+
+Three project-scoped resources:
+
+```
+Epic (the vision — its own resource, §1)
+  └── epictask  — a roadmap node; tasks hang off it
+        ├── task — the unit of work / execution
+        └── task
+  └── epictask ── chains to other epictasks (the roadmap web)
+```
+
+### `epictask`
+- A roadmap node. **Tasks link to an epic task** (a task belongs-to / serves an
+  epic task).
+- **Epic tasks chain to each other** (dependencies). Visualizing all epic tasks
+  yields a **spider web of roadmap** — not a flat sequence, but a dependency
+  graph. This is the navigational/planning layer.
+
+### `task`
+- The unit of work, owned by an epictask.
+- Carries the standard lifecycle from round 1 (InProgress → SelfCheck →
+  AwaitingReview → accept → Merged → Reopened-on-failure).
+- **Contains artifacts** (see §4).
+
+### Threading the vision through
+Because tasks link to epictasks and epictasks belong to an Epic, every task can
+resolve "**what am I serving and what does done-for-this look like**" by walking
+up the chain to the Epic + its agreed "done" criteria. Tier-2 (vision) DoD is
+therefore **reachable from every task**, not bolted on.
+
+---
+
+## 3. Reopen vs new-task — the mechanism
+
+The Epic-comparison diff produces both, distinguished by *why* the gap exists:
+
+| Gap cause | Outcome |
+|---|---|
+| A task **claimed** to cover a piece but didn't deliver it right (acceptance criteria unmet) | **Reopen** the task (send back with the directional comment) |
+| A piece of the Epic was **never decomposed into a task** at all (breakdown gap) | **New task** under the relevant epictask |
+| A piece needs **joint effort / the fix is hard** | **`exec` joint session** (plus optionally reopen/new task after) |
+
+The loop repeats until the Epic reaches a terminal state: 100% delivered, or
+delivered-with-accepted-tradeoffs.
+
+---
+
+## 4. Artifacts + IPython-style context (prime-agent philosophy)
+
+Borrowing from
+[PrimeIntellect prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)'s
+**"context as variables / prompt-as-a-variable"** model:
+
+### Artifacts are objects, not plain text
+Each task can contain **artifacts**: `files|test`, logs, and also **PR and
+commits** — but as **structured objects with an `expand` operation**, **not
+stored/loaded as plain text**.
+
+- A PR or commit is an object; the LLM can `expand` it *on demand* to get the
+  detail (diff, files, messages). It is not dumped into context eagerly.
+- "Catting" something **materializes it into a variable/artifact** — a named,
+  retrievable reference — rather than auto-injecting its full text into the
+  LLM context.
+
+**The rule: context does NOT auto-populate from artifact content.** You pull
+what you need; nothing is eagerly loaded.
+
+### Eviction / flush priority (what to drop first)
+When context must be flushed/compacted, the retention hierarchy is:
+
+1. **Keep the user's words the longest** — highest retention.
+2. Next, keep what the **agent said**.
+3. Next, the **artifact context** — and this is *safe to evict first* because
+   artifacts are **durably stored**; their content can always be **recovered
+   on demand via `expand`**.
+
+So eviction order is **user > agent > artifact-context**, justified precisely
+by recoverability: artifact content isn't lost, it's retrievable — so dropping
+it from live context costs nothing permanent.
+
+---
+
+## 5. Open questions / tensions to resolve
+
+1. **Epic as a resource vs a "prompt"** — does the Epic get its own resource
+   type (with RBAC + `ResourceRevision`), or reuse the project `prompt`/`skill`
+   mechanism? Lean: own resource — it's the audit/source-of-truth for "is this
+   done," distinct from context-injection prompts.
+2. **Epic-task `done` criteria** — do epictasks also carry their own
+   acceptance criteria, or is all "done" defined at the Epic level? Lean: Epic
+   defines overall done; epictasks carry the *decomposed* subset, so the spider
+   web can show per-node completeness.
+3. **Artifact storage location** — consistent with LE-8/LE-5: server-side,
+   mcpctl-owned, keyed by commit/task. Confirm artifacts live outside git (for
+   binaries/build outputs) vs git-native for commits/PRs (which stay in the
+   repo/PR API and are referenced as objects, not copied).
+4. **What counts as "artifact context" for eviction** — an `expand`ed artifact
+   that *has* been pulled into context: once the turn ends, does it return to
+   "stored-only" (safe to evict) or persist as agent-context? Lean: after the
+   turn it is stored-only again (evict first), because it's recoverable.
+5. **Naming (LE-7)** — `epictask` vs `epic-task` vs `epic_task`; and whether
+   `task` collides with the repo's `.taskmaster` tasks. Needs a naming decision.