History — frozen, read-only

This tree is archaeology. It preserves the reasoning path that produced Arius's current design, in the formats the project used before settling on ADRs + design docs. Nothing here is maintained. It is kept because the narratives hold intent (rejected alternatives, the "why") that the living docs summarise but do not reproduce in full.

If you want the current truth, start at ../README.md (the doc map), ../design/, and ../decisions/. Come here only to understand why a decision was made the way it was.

How the documentation evolved

Arius's docs grew through four overlapping eras (dates from git history):

Era	Window	System	Where its durable intent lives now
1	2026-03-10 → 2026-06-08	OpenSpec — capability specs + per-change proposal/design/tasks	Mechanical specs collapsed into ../design/; rationale lifted into ADRs 0013, 0014, 0015, 0016, 0017. Change narratives frozen in openspec-archive/.
2	2026-04-19 → 2026-05-11	Superpowers — RFC-style design docs	Superseded by ADRs 0001, 0006, 0008, 0009. Frozen in superpowers/.
3	2026-04-24 → today	ADRs (MADR)	Live — this is the current decision home: ../decisions/.
4	2026-06-10 → today	Full agentic — saved plans + conversations	Implemented in code; intent folded into ADRs and ../design/. Plans frozen in agentic-plans/.

The decisive moment was 2026-04-24 (feat: replace superpower specs & plans with MADR): the superpowers plans were deleted and ADRs became the decision record. OpenSpec persisted alongside ADRs until 2026-06-08, after which the project worked "full agentic" and saved its plans rather than maintaining a spec system.

What's here

• openspec-archive/ — the proposal.md + design.md of each completed OpenSpec change (the tasks.md checklists and Gherkin spec deltas were dropped as non-durable). The design.md files carry the richest rejected-alternatives reasoning — e.g. the foundational 2026-03-24-arius-core-foundation, 2026-03-31-aes256gcm-encryption, and the chunk-index scalability arc (2026-05-29, 2026-06-02, 2026-06-08).
• superpowers/ — the four 2026-04 superpowers design docs (shared test infrastructure, the representative E2E workflow, filetree staging/build, the core path-typing sweep), plus the later 2026-06-29 snapshot-list-and-diff design spec + implementation plan (the superpowers brainstorming/writing-plans skills are still in use, and per the repo's AGENTS.md their artifacts are frozen here). Its durable intent lives in read-queries (the streaming SnapshotsListQuery and the MECE SnapshotDiffQuery), encryption (the passphrase-mismatch RepositoryEncryptionException), the CLI host doc, and the CLI guide. The 2026-07-04 → 2026-07-06 jobs-progress design + its implementation plans — UX design, Plan 1 foundation, Plan 2 Api lifecycle & realtime protocol, Plan 3 Web rework — reworked archive/restore progress (byte-weighted JobSink, adaptive ETA, the Jobs overview + /jobs/:id detail page). A follow-on xhigh code review found 15 mostly-untested defects, addressed by the test-harness design and its plans — Plan 1 harness, Plan 2 representation, Plan 3a lifecycle, Plan 3b client + Vitest, Plan 3c browser-hermetic e2e — which stood up a scripted-fake-Core harness (Arius.Api.Integration.Tests + Arius.Api.FakeTestHost) and a Vitest + hermetic-Playwright web test tier. Durable intent landed in ADR-0022 (the harness decision), cross-cutting/testing.md (the harness + Web test tiers), and the web host doc (the job model, cost handshake, and IRepositoryCoreComposer seam). A follow-on 2026-07-12 → 2026-07-13 round — the adaptive, phase-aware ETA plan — finished the half-built JobSink.SetPhase stage stepper (forward-only ordinal + the new FinalizingSnapshotEvent) and modelled the archive ETA as max(hashEta, uploadEta) over two elapsed-scaled EMAs, flagging it EtaIsUpperBound until hashing completes. Its durable intent landed in events-and-progress.md (FinalizingSnapshotEvent), the web host doc (the phase stepper and adaptive-ETA model), and the archive-command / memory-boundedness / performance design docs (the companion filePairChannel unbounding, so the scan total surfaces before hashing catches up). A final 2026-07-21 round — the archive progress / ETA fixes design — read four anomalies (backwards bar, a 58 h ETA spike, pct/ETA disagreement, a 16 GB/s throughput reading) straight off an [ETA] debug trace of a real 75-minute run: pct became the monotonic (uploaded+deduped)/total, the ETA's upload denominator became the queued-new total (exact once the new RoutingCompleteEvent fires), the reported throughput became the binding term's rate, and EtaIsUpperBound was renamed EtaIsProvisional — the tightened denominator is no longer a bound in either direction.
• agentic-plans/ — PLAN/CONVO/report markdown saved during the agentic era (raw .txt conversation transcripts and UI mockup assets were dropped). Includes the dynamic-shard-length and chunk-index scalability plans that fed ADR-0015, and the zstd evaluation that fed ADR-0012. The two latest were lifted out of openspec/changes/ (a leftover habit — OpenSpec ended 2026-06-08): the v5→v7 migration tool plan — its durable intent now lives in the migration design doc, plus the legacy AES-256-CBC read back-compat (PBKDF2 = 10,000) documented in encryption — and the chunk-index repair/flush unification conversation, folded into chunk-index and repair-chunk-index. The follow-up migration sidecar + historical states conversation (the archive-tier chunk metadata sidecar and the v3/v5 historical-snapshot replay) landed in ADR-0018 and the migration design doc. The fix-snapshot-totalsize investigation (snapshot size metrics, then making the web Statistics figures complete and fast) and the Arius.Web tweaks conversation (the snapshot bar promotion, Statistics redesign, Properties drawer with passphrase rotation + delete, and the Karma→Playwright move) landed in the chunk-index / read-queries / web host design docs and the web-ui guide. The web per-repo logging plan (routing Web→Core operations to a shared per-repository rolling log file in the same ~/.arius/.../logs/ location the CLI writes) landed in the logging and web host design docs and the deployment guide. The file/folder filter plan (configurable archive exclusions, defined centrally in Arius.Core to avoid host drift) landed in ADR-0019 and the archive-command design doc. The storage accounts & provider-agnostic pricing plan (storage-account region management + edit flyout, a region-aware cost-by-tier view, real Azure Retail Prices rates with Cool/Cold retrieval + egress in the restore estimate, and moving Azure pricing into Arius.AzureBlob behind the IStorageCostEstimator port) landed in ADR-0020, the cost estimation design doc, the restore-command / read-queries / web host design docs, and the web-ui guide. The fast-hash + hashcache plan (with its design and the hardening code-review transcript) — an opt-in --fast-hash that skips re-reading unchanged binaries via a per-repository SQLite hashcache, plus making --write-pointers opt-in — landed in ADR-0021, the hashcache and archive-command design docs, and the CLI and web-ui guides.