feat: add durable activity history

README.md

@@ -209,6 +209,7 @@ fclt ai loop activity --project
 fclt ai loop activity --project --json
 fclt ai loop activity --all --json
 fclt ai loop resolve <activity-action-locator> --json
+fclt ai loop history --project --since 2026-01-01T00:00:00Z --json
 ```
 
 The activity snapshot explains what agents captured, what sources were checked,
@@ -219,6 +220,11 @@ Aggregate actionable items may carry an opaque locator. Resolution revalidates
 the exact current scope and lifecycle revision and returns a plain-language
 plan without guessing a root or performing a mutation.
 
+Use `loop history` for a bounded multi-run timeline. It returns append-only
+event lineage, opaque cross-scope identities, cursor pagination, and explicit
+snapshot-only, pruned, corrupt, or truncated coverage. The current activity
+snapshot remains the fast default.
+
 ### 3. Inspect existing AI state
 
 Start read-only:

docs/README.md

@@ -22,6 +22,7 @@ Start with [Writeback and evolution](./writeback-evolution.md) for the product's
 - [Managed mode](./managed-mode.md): when to let `fclt` write tool files, and how adoption works.
 - [Security and trust](./security-trust.md): source trust, audit, secrets, and commit hygiene.
 - [Automations](./automations.md): recurring Codex loops for learning review, evolution review, and tool-call audit.
+- [Activity history](./activity-history.md): bounded multi-run timelines, lineage identities, retention, and privacy rules.
 - [Command reference](./reference.md): command groups and common flags.
 - [Roadmap](./roadmap.md): current product gaps and planned work.
 

docs/activity-history.md

@@ -0,0 +1,87 @@
+# Activity history
+
+`fclt ai loop activity` remains the fast current-state snapshot. Use `fclt ai
+loop history` when a consumer needs to explain how an item changed across
+runs.
+
+```bash
+fclt ai loop history --json
+fclt ai loop history --project --since 2026-01-01T00:00:00Z --json
+fclt ai loop history --item family:SF-example --limit 50 --json
+fclt ai loop history --scope-id project:0123456789abcdef --event verification --json
+```
+
+The command defaults to all configured scopes. Use `--global` or `--project`
+for one scope. `--since`, `--until`, `--scope-id`, `--item`, and repeatable
+`--event` flags narrow the query. Results are newest first. `--limit` accepts
+1–200 records; pass `page.nextCursor` back through `--cursor` for the next
+page.
+
+## Contract
+
+The JSON response is the version 1 `activity-history` contract. It contains:
+
+- immutable event deltas, not copies of the current activity card
+- run records for the events on the current page
+- opaque scope, resource, family, and proposal identities
+- optional lineage heads when `--item` is present
+- per-scope availability, corruption, migration, and retention state
+- pagination and separate truncation metadata
+
+Event types are `run`, `discovery`, `observation`, `correlation`,
+`disposition`, `proposal`, `review`, `application`, `verification`,
+`effectiveness`, `regression`, `supersession`, and `resolution`. The `action`
+field carries the concrete transition, such as `repeated`, `task`, `defer`,
+`rejected`, `applied`, `verified`, `improved`, `regressed`, `superseded`, or
+`resolved`.
+
+Every event references one recorded run. The run record carries scope, trigger,
+status, loop revision, config revision, reconciliation window, and coverage
+counts. Resource events carry only the changed field and bounded safe context.
+Consumers should join events to run records on the composite `(scopeId,
+runId)` key because run IDs are only unique within a scope. Resource lineage
+joins use `resource.id`; consumers should not infer lineage from titles or
+internal IDs.
+
+When correlation merges or another transition supersedes a prior resource,
+`relatedResourceIds` contains the opaque successor identity. This keeps branch
+lineage collision-safe without exposing machine or source identity.
+
+An item filter can match a returned resource ID or a safe scope-local item,
+family, or proposal ID. The result sets `lineage.ambiguous` when the same local
+ID exists in more than one scope. Use the opaque `scopeId` to disambiguate it.
+
+## Storage and retention
+
+History is machine-local runtime state. Each completed, degraded, or failed
+non-preview loop run writes one immutable segment. Rewriting the same run is
+idempotent and a checksum mismatch is refused. Preview runs do not write
+history.
+
+The default retention policy keeps 365 days, at most 10,000 events, and at most
+2,000 current lineage heads per scope. Retention removes whole oldest segments
+and least-recently observed heads. The manifest records pruned event, segment,
+and head counts plus the last pruned event boundary. A query that asks for data
+before that boundary reports partial coverage; an item-lineage query also
+reports partial coverage after any head pruning.
+
+The first version does not backfill from activity snapshots, technical loop
+reports, writeback journals, or proposal files. Existing installations begin
+with a truthful `snapshot-only` boundary. A query is complete only when its
+explicit `--since` value is inside the retained version 1 window and every
+selected scope is readable.
+
+## Privacy and integration
+
+The portable response excludes canonical roots, runtime paths, raw source
+payloads, credentials, URL query strings, and local file links. It reports
+corrupt, missing, omitted, pruned, and scan-limited history instead of silently
+dropping it.
+
+Core history reads and writes do not call external trackers or vendors. Export
+is not part of this contract. A future export must be a separate explicit,
+redacted, reviewable operation.
+
+Human interfaces should consume this CLI/JSON contract directly. They should
+not reconstruct history from runtime files or treat a current activity snapshot
+as a timeline.

docs/automations.md

@@ -42,6 +42,7 @@ fclt ai loop enable --project
 fclt ai loop status --project --json
 fclt ai loop run --project --json
 fclt ai loop activity --json
+fclt ai loop history --project --since 2026-01-01T00:00:00Z --json
 fclt ai loop disable --project
 ```
 
@@ -88,6 +89,12 @@ and next actions without absolute machine paths. Use `fclt ai loop activity
 configured project, or add `--global`/`--project` to inspect one scope. Use the
 technical loop report only for diagnostics.
 
+Multi-run history is separate from the latest activity snapshot. Each
+non-preview run appends an immutable event segment, and `loop history` provides
+bounded timeline and lineage reads with explicit pagination, retention,
+migration, and degraded-coverage metadata. Downstream interfaces should use
+that command instead of reconstructing history from runtime files.
+
 ## Suggested Cadence
 
 - daily or per-project `learning-review` for durable signal

docs/reference.md

@@ -123,6 +123,7 @@ fclt ai loop disable [--dry-run] [--json]
 fclt ai loop status [--json]
 fclt ai loop activity [--all|--global|--project] [--json]
 fclt ai loop resolve <activity-action-locator> [--json]
+fclt ai loop history [--all|--global|--project] [--since <date>] [--until <date>] [--item <id>] [--scope-id <opaque-id>] [--event <type>] [--limit <1-200>] [--cursor <cursor>] [--json]
 fclt ai loop run [--since <date>] [--until <date>] [--source <id>] [--dry-run] [--scheduled] [--json]
 ```
 
@@ -163,6 +164,15 @@ Older or non-actionable items without a locator remain handoff-only. See
 [Activity action locators](./activity-action-locators.md) for versioning and
 error semantics.
 
+`loop history` is the bounded version 1 multi-run timeline and lineage
+contract. It stores immutable per-run event segments in machine-local runtime
+state and returns delta events rather than copying current activity items.
+Queries are newest first and cursor-paginated. Scope, time, item, and event-type
+filters are explicit. Missing pre-history, retention pruning, corruption, and
+bounded omissions remain visible in `coverage` and `truncation`. See
+[Activity history](./activity-history.md) for the schema, identity, retention,
+and privacy contract.
+
 `loop enable` is an explicit opt-in that installs an fclt-owned Codex
 automation. The loop persists the full current queue, emits a delta for
 notifications, retries bounded reconciliation failures, reports scheduler