Lesson 30 — Facts, claims, and meaningful activity

Outcome

Build a human-readable activity feed that is useful without pretending agent narration is verified fact.

Why this comes now

The central UX problem is returning awareness without reading transcripts. We waited until real Runs exist so activity is based on evidence, not imagined schemas.

Understand

Two tiers work well: deterministic Steps from observed events, plus coarse agent-authored phases/intent/conclusions where the selected strategy can provide or accept them. The data model preserves Fact vs Claim. If narration is absent, Forge falls back to facts honestly.

Do not run a second summarizer model over every event by default; it adds cost/latency and can fabricate context.

Build the real project

1. Define ActivityItem projection from normalized AgentEvents.
2. Group low-level tool lifecycle into useful Steps.
3. Add optional native-plan/intent events as Claims when strategy supports them.
4. Add injected narration marker only for findings/phase boundaries not already provided natively.
5. Build paged Activity UI with collapsed detail and raw-evidence drill-down.
6. Preserve source Run/Turn and evidence kind.
7. Add tests showing missing narration still produces a fact-only feed.

Completion gate

A real Task's activity can be understood at a glance; clicking deeper reaches normalized/raw evidence; a Claim is never rendered/persisted as Fact.

Pitfalls to avoid

Do not infer “Found reusable retry infrastructure” from a Bash command. Do not display every token/tool delta as a top-level feed row. Do not hide absence of narration by generating fake summaries.

References

Sculptor structured UX: https://github.com/imbue-ai/sculptor/blob/main/docs/help/integrated_harnesses.md ; archived Forge research ADR-0011/0012 in docs/archive/01-previous-forge-overview.md.

Checkpoint

Use the feed for real work and record which low-level steps are noise. Tune projection from evidence.