Bootstrap project and safe work-item workflow

delivery_backlog/stories/US01-01-donor-characterization.md

@@ -0,0 +1,20 @@
+# US01-01 — Inventory and Characterize Donor Code
+
+Epic: [E01](../E01-shared-identity-inventory.md)
+
+As a maintainer, I want a donor ledger and characterization suite for the current CLI
+implementations so proven behavior is reused deliberately instead of rewritten.
+
+## Acceptance criteria
+
+- Relevant functions in both CLI codebases are classified as reuse, extract, refactor,
+  or replace, with rationale and target module.
+- The ledger covers discovery, hashing, imaging, NSFW, vision, EXIF, database, UI,
+  configuration, logging, cancellation, and error behavior.
+- Representative current outputs are captured against stable fixture IDs.
+- No legacy file is moved or archived in this story.
+
+## Automated tests
+
+- Characterization tests run against current donor entry points and core functions.
+- A ledger-lint test rejects missing source references, target locations, or test IDs.

delivery_backlog/stories/US01-02-app-database-foundation.md

@@ -0,0 +1,24 @@
+# US01-02 — Establish Application and Database Foundation
+
+Epic: [E01](../E01-shared-identity-inventory.md)
+
+As an operator, I want the API, worker configuration, and database lifecycle to start
+consistently so later services share one durable foundation.
+
+## Acceptance criteria
+
+- FastAPI factory, typed configuration, SQLAlchemy sessions, Alembic, WAL, foreign
+  keys, structured logging, and readiness are configured.
+- Stable asset IDs, path occurrences, versions, and audit timestamps have migrations.
+- Secrets are referenced through configuration and never returned or logged.
+- Startup and shutdown leave no leaked worker or database resources.
+
+## Automated tests
+
+- Migrations pass from an empty database and supported legacy schema snapshots.
+- Process-level integration tests verify readiness, restart, WAL, foreign keys, and
+  clean shutdown.
+
+## Dependencies
+
+- US01-01

delivery_backlog/stories/US01-03-inventory-identity.md

@@ -0,0 +1,23 @@
+# US01-03 — Discover and Reconcile Stable Assets
+
+Epic: [E01](../E01-shared-identity-inventory.md)
+
+As a user, I want scans to discover eligible photos and retain identity across moves
+so reorganizing folders does not lose prior work.
+
+## Acceptance criteria
+
+- Donor discovery and reconciliation logic is extracted behind `InventoryService`.
+- All supported roots use one boundary and exclusion policy; unsafe symlink paths fail.
+- New, moved, copied, replaced, missing, active, and archived occurrences are distinct.
+- Enumeration is deterministic and rescanning unchanged input is idempotent.
+
+## Automated tests
+
+- Unit/property tests cover path normalization, boundaries, and reconciliation.
+- Integration tests move, copy, replace, remove, and rescan fixture assets, asserting
+  stable IDs and exact durable states after restart.
+
+## Dependencies
+
+- US01-02

delivery_backlog/stories/US01-04-duplicate-engine.md

@@ -0,0 +1,24 @@
+# US01-04 — Detect and Decide Duplicates
+
+Epic: [E01](../E01-shared-identity-inventory.md)
+
+As a user, I want explainable duplicate clusters and reversible decisions so redundant
+copies are excluded without collapsing distinct photos automatically.
+
+## Acceptance criteria
+
+- Donor exact, normalized-pixel, and perceptual hash behavior is extracted and
+  versioned.
+- Confidence bands distinguish automatic exact matches from fuzzy review candidates.
+- Canonical, variant, not-duplicate, and deferred decisions persist with evidence.
+- New contradictory members reopen reviewed clusters; canonical links cannot cycle.
+
+## Automated tests
+
+- Golden corpus tests assert hash relationships and confidence classes.
+- Property/integration tests cover clustering, negative links, reversals, new members,
+  and persistence after restart.
+
+## Dependencies
+
+- US01-03

delivery_backlog/stories/US01-05-thumbnail-service.md

@@ -0,0 +1,24 @@
+# US01-05 — Generate and Serve Managed Thumbnails
+
+Epic: [E01](../E01-shared-identity-inventory.md)
+
+As a reviewer, I want safe, correctly oriented previews so I can compare photos without
+exposing arbitrary filesystem paths.
+
+## Acceptance criteria
+
+- Donor decode, orientation, resize, and HEIC behavior is reused where compatible.
+- Thumbnails are requested by asset ID, cached atomically, quota-managed, and
+  invalidated when source identity changes.
+- Corrupt, oversized, missing, and unsupported inputs produce bounded typed errors.
+- Requests cannot escape configured roots or access excluded paths.
+
+## Automated tests
+
+- Golden tests assert orientation, dimensions, transparency handling, and cache keys.
+- Integration tests cover concurrent generation, corruption, invalidation, eviction,
+  and path attacks.
+
+## Dependencies
+
+- US01-03

delivery_backlog/stories/US01-06-inventory-review-ui.md

@@ -0,0 +1,25 @@
+# US01-06 — Review Inventory and Duplicates in the Browser
+
+Epic: [E01](../E01-shared-identity-inventory.md)
+
+As a user, I want to browse inventory and compare duplicate candidates visually so I
+can make informed canonical decisions.
+
+## Acceptance criteria
+
+- Inventory lists are paged, filterable, keyboard accessible, and use stable URLs.
+- Duplicate comparison shows oriented previews, metadata evidence, confidence, and
+  synchronized comparison controls.
+- Fuzzy decisions require explicit confirmation; stale versions receive a visible
+  conflict and never mutate state.
+- Reloading restores the selected view and persisted decisions.
+
+## Automated tests
+
+- Component tests cover state, routing, and API error presentation.
+- Playwright tests cover keyboard review, fuzzy confirmation, stale conflicts, and
+  persistence after reload.
+
+## Dependencies
+
+- US01-04, US01-05

delivery_backlog/stories/US01-07-phase-a-e2e.md

@@ -0,0 +1,24 @@
+# US01-07 — Automate Phase A End-to-End Acceptance
+
+Epic: [E01](../E01-shared-identity-inventory.md)
+
+As a delivery owner, I want reproducible Phase A end-to-end tests so identity,
+inventory, duplicates, and thumbnails cannot regress unnoticed.
+
+## Acceptance criteria
+
+- The harness launches the real API and worker with a fresh database and deterministic
+  temporary fixture library.
+- Journeys cover scan, exclusion, move reconciliation, exact/fuzzy duplicate review,
+  thumbnail orientation, canonical selection, reload, and full process restart.
+- API and durable database state are asserted after restart.
+- Story IDs US01-01 through US01-06 map to passing automated tests.
+
+## Automated tests
+
+- One documented command runs Phase A API and Playwright suites without network access.
+- CI retains diagnostics on failure and rejects skipped, flaky, or unexercised fixtures.
+
+## Dependencies
+
+- US01-01 through US01-06

delivery_backlog/stories/US02-01-safety-ui-donors.md

@@ -0,0 +1,22 @@
+# US02-01 — Extract Safety and Existing Web UI Donors
+
+Epic: [E02](../E02-unified-workflow-shell.md)
+
+As a maintainer, I want safety logic and proven web interactions extracted from the
+existing tools so the unified workflow retains working behavior and visual language.
+
+## Acceptance criteria
+
+- The donor ledger maps scoring, thresholds, decisions, EXIF keywords, filters,
+  layouts, tokens, keyboard controls, and error states to new modules.
+- Behavior changes required by stable identity or shared jobs are documented.
+- Shared modules have no dependency on archived entry points.
+
+## Automated tests
+
+- Characterization tests compare donor and extracted behavior on the same fixture IDs.
+- Snapshot/interaction tests cover reused design tokens and critical controls.
+
+## Dependencies
+
+- E01 complete

delivery_backlog/stories/US02-02-durable-jobs.md

@@ -0,0 +1,22 @@
+# US02-02 — Persist and Coordinate Durable Jobs
+
+Epic: [E02](../E02-unified-workflow-shell.md)
+
+As an operator, I want jobs and item progress stored durably so work can resume after
+browser, API, or worker interruption.
+
+## Acceptance criteria
+
+- Job, item, event, attempt, progress, cancellation, and terminal states are persisted.
+- Commands support idempotency keys and atomic state transitions.
+- Prerequisites and one-mutating-job policy produce explicit blockers.
+- Progress derives from durable item state rather than browser memory.
+
+## Automated tests
+
+- State-machine/property tests reject invalid transitions and duplicate terminal state.
+- Repository tests cover concurrent idempotent submission and restart persistence.
+
+## Dependencies
+
+- US01-02

delivery_backlog/stories/US02-03-worker-recovery.md

@@ -0,0 +1,22 @@
+# US02-03 — Execute Jobs with Leases, Locks, and Recovery
+
+Epic: [E02](../E02-unified-workflow-shell.md)
+
+As an operator, I want workers to claim, cancel, and recover jobs safely so crashes or
+duplicate workers cannot corrupt state.
+
+## Acceptance criteria
+
+- Workers use leases, heartbeats, fencing tokens, bounded queues, and typed lanes.
+- Cancellation is cooperative and leaves resumable or terminal item states.
+- Lock ordering prevents conflicting analysis, EXIF, rename, upload, and archive work.
+- A recovered job rejects late commits from its former worker.
+
+## Automated tests
+
+- Process tests kill workers, expire leases, recover jobs, and attempt stale commits.
+- Randomized concurrency tests assert no deadlocks, duplicate completion, or lost events.
+
+## Dependencies
+
+- US02-02

delivery_backlog/stories/US02-04-job-api-events.md

@@ -0,0 +1,23 @@
+# US02-04 — Expose Job APIs and Activity Events
+
+Epic: [E02](../E02-unified-workflow-shell.md)
+
+As a frontend client, I want versioned job commands, status APIs, and activity events
+so the browser can operate workflows without HTML responses or internal imports.
+
+## Acceptance criteria
+
+- `/api/v1` exposes typed job start, status, cancel, blocker, and event contracts.
+- Operational endpoints return JSON; the event endpoint returns SSE with resumable IDs.
+- SSE reconnects without duplicate/lost durable events and polling is sufficient as a
+  fallback.
+- Errors use the shared JSON envelope and correct status codes, including `409`.
+
+## Automated tests
+
+- OpenAPI/contract tests validate schemas, status codes, errors, and content types.
+- Black-box tests cover SSE disconnect/reconnect, polling, idempotency, and cancellation.
+
+## Dependencies
+
+- US02-02, US02-03

delivery_backlog/stories/US02-05-frontend-shell.md

@@ -0,0 +1,24 @@
+# US02-05 — Build the Static Application Shell
+
+Epic: [E02](../E02-unified-workflow-shell.md)
+
+As a user, I want a fast, navigable application shell so all workflow views share one
+consistent interface without server-generated operational HTML.
+
+## Acceptance criteria
+
+- `index.html`, CSS, and modular JavaScript are separate static files.
+- Shared API client, store, router, error handling, cancellation, and SSE/polling
+  adapters are implemented.
+- Navigation routes restore current view and filters after reload.
+- HTML fallback never intercepts `/api/v1` requests.
+
+## Automated tests
+
+- JavaScript tests cover API errors, store transitions, routing, and event fallback.
+- Browser tests assert asset loading, deep links, reload, JSON-only APIs, and no
+  unexpected console/network errors.
+
+## Dependencies
+
+- US02-04

delivery_backlog/stories/US02-06-workflow-views.md

@@ -0,0 +1,25 @@
+# US02-06 — Deliver Workflow, Safety, Library, Analysis, and Stats Views
+
+Epic: [E02](../E02-unified-workflow-shell.md)
+
+As a user, I want one workflow home and migrated operational views so I can understand
+readiness, review safety, browse assets, run analysis, and inspect results.
+
+## Acceptance criteria
+
+- Workflow cards show counts, blockers, last run, action, and details without relying
+  on color alone.
+- Safety decisions persist and prevent NSFW assets from reaching vision analysis while
+  retaining verified upload eligibility.
+- Library, Analyze, and Stats preserve useful donor features on shared APIs.
+- Read-only browsing remains available during jobs; conflicting actions explain why
+  they are disabled.
+
+## Automated tests
+
+- View tests cover counts, filters, blockers, decisions, progress, errors, and reload.
+- Integration tests assert provider-call privacy and verified safety EXIF behavior.
+
+## Dependencies
+
+- US02-01, US02-05

delivery_backlog/stories/US02-07-phase-b-e2e.md

@@ -0,0 +1,23 @@
+# US02-07 — Automate Phase B End-to-End Acceptance
+
+Epic: [E02](../E02-unified-workflow-shell.md)
+
+As a delivery owner, I want Phase B workflow automation so durable jobs and migrated
+views are proven through real process and browser boundaries.
+
+## Acceptance criteria
+
+- Journeys cover shell loading, workflow blockers, safety review, analysis start,
+  progress, SSE reconnect, polling fallback, cancellation, resume, and error inspection.
+- A second conflicting mutation is rejected while read-only browsing continues.
+- NSFW fixture IDs never reach the fake vision provider and decisions survive restart.
+- Story IDs US02-01 through US02-06 map to passing automated tests.
+
+## Automated tests
+
+- One documented command runs Phase B API, worker-recovery, and Playwright suites.
+- The Phase A suite runs unchanged as a required regression gate.
+
+## Dependencies
+
+- US02-01 through US02-06

delivery_backlog/stories/US03-01-album-evidence.md

@@ -0,0 +1,23 @@
+# US03-01 — Aggregate Album Evidence
+
+Epic: [E03](../E03-album-proposals.md)
+
+As a user, I want album suggestions based on summarized photo evidence so names reflect
+the folder without exposing unnecessary raw responses.
+
+## Acceptance criteria
+
+- The service aggregates canonical, eligible asset descriptions, tags, dates,
+  locations, people counts, and current folder identity.
+- Missing, conflicting, deferred, duplicate, and NSFW evidence follows documented rules.
+- Aggregation is versioned, deterministic, paged where needed, and invalidated by
+  relevant asset changes.
+
+## Automated tests
+
+- Unit/property tests cover aggregation, exclusions, conflicts, ordering, and versions.
+- Repository tests verify results before and after relevant asset changes.
+
+## Dependencies
+
+- E02 complete

delivery_backlog/stories/US03-02-naming-policy.md

@@ -0,0 +1,22 @@
+# US03-02 — Define Album Naming Policy
+
+Epic: [E03](../E03-album-proposals.md)
+
+As a user, I want configurable naming templates and validation so proposed album names
+are readable and safe on supported filesystems.
+
+## Acceptance criteria
+
+- Templates define allowed evidence, formatting, length, separators, and fallbacks.
+- Validation handles forbidden characters, reserved names, whitespace, Unicode,
+  case-insensitive collisions, existing destinations, and empty results.
+- Validation returns structured issues and suggestions without mutating files.
+
+## Automated tests
+
+- Property tests generate names across platforms and prove paths stay inside the root.
+- Golden cases cover valid names, collisions, normalization, and template fallbacks.
+
+## Dependencies
+
+- US03-01

delivery_backlog/stories/US03-03-proposal-generation.md

@@ -0,0 +1,25 @@
+# US03-03 — Generate and Persist Versioned Proposals
+
+Epic: [E03](../E03-album-proposals.md)
+
+As a user, I want AI-assisted album proposals with rationale and confidence so I can
+evaluate suggestions before approving them.
+
+## Acceptance criteria
+
+- A provider adapter receives only the minimum aggregated evidence and returns a
+  validated structured proposal.
+- Proposal, evidence version, model/prompt version, rationale, confidence, edits, and
+  approval state are durable.
+- Malformed, rate-limited, failed, duplicate, and stale responses are explicit and
+  safely retryable.
+- Approval validates the latest proposal version and performs no rename.
+
+## Automated tests
+
+- Deterministic fake-provider tests cover success, malformed output, retry, and failure.
+- API tests cover creation, edits, optimistic conflicts, approval, and restart.
+
+## Dependencies
+
+- US03-01, US03-02

delivery_backlog/stories/US03-04-proposal-ui.md

@@ -0,0 +1,24 @@
+# US03-04 — Review and Approve Proposals in the Browser
+
+Epic: [E03](../E03-album-proposals.md)
+
+As a user, I want to inspect evidence, edit a proposal, and approve it so I retain
+control over album naming.
+
+## Acceptance criteria
+
+- The view shows source album, suggested name, evidence summary, rationale, confidence,
+  validation issues, and affected count.
+- Edits validate promptly; collisions and invalid names are actionable.
+- Approval requires explicit action and rejects stale state visibly.
+- Reload preserves edits and approval state through the API.
+
+## Automated tests
+
+- UI tests cover editing, errors, collision guidance, approval, stale conflict, and
+  keyboard operation.
+- Playwright asserts no file path changes occur during proposal approval.
+
+## Dependencies
+
+- US03-03

delivery_backlog/stories/US03-05-phase-c-e2e.md

@@ -0,0 +1,22 @@
+# US03-05 — Automate Phase C End-to-End Acceptance
+
+Epic: [E03](../E03-album-proposals.md)
+
+As a delivery owner, I want automated proposal journeys so generation, editing, and
+approval remain deterministic and non-mutating.
+
+## Acceptance criteria
+
+- Journeys cover evidence aggregation, success, provider failure, invalid name,
+  collision, editing, stale approval, valid approval, reload, and restart.
+- Tests assert provider inputs, persisted versions, and unchanged fixture paths.
+- Story IDs US03-01 through US03-04 map to passing automated tests.
+
+## Automated tests
+
+- One command runs Phase C API and Playwright suites with the deterministic provider.
+- Phase A–B end-to-end suites remain green.
+
+## Dependencies
+
+- US03-01 through US03-04

delivery_backlog/stories/US04-01-rename-plan.md

@@ -0,0 +1,23 @@
+# US04-01 — Build and Export Rename Plans
+
+Epic: [E04](../E04-guarded-renaming.md)
+
+As a user, I want a complete validated rename plan before mutation so I can understand
+every source, destination, collision, and blocker.
+
+## Acceptance criteria
+
+- Approved album proposals produce itemized plans with asset IDs, source/destination,
+  expected hashes, versions, and required operations.
+- Validation detects missing/changed sources, duplicate targets, case-only and Unicode
+  collisions, root escapes, symlinks, and cross-filesystem behavior.
+- A portable JSON export contains no credentials and has a schema version/checksum.
+
+## Automated tests
+
+- Property tests validate collision-free plans and asset-set preservation.
+- API/golden tests cover valid, invalid, stale, case-only, Unicode, and exported plans.
+
+## Dependencies
+
+- E03 complete

delivery_backlog/stories/US04-02-rename-journal.md

@@ -0,0 +1,23 @@
+# US04-02 — Journal Rename State and Preconditions
+
+Epic: [E04](../E04-guarded-renaming.md)
+
+As an operator, I want every rename transition journaled durably so interrupted work
+can be diagnosed and recovered without guessing.
+
+## Acceptance criteria
+
+- Plan and item state machines record preconditions, intent, attempts, outcomes,
+  timestamps, fencing tokens, and verification evidence.
+- Journal writes occur before filesystem mutations and terminal transitions are
+  idempotent.
+- Startup classifies incomplete transitions as resumable, rollback-safe, or manual.
+
+## Automated tests
+
+- State-machine tests cover all valid/invalid transitions and repeated recovery.
+- Migration/repository tests prove durable state after process restart.
+
+## Dependencies
+
+- US04-01, US02-03

delivery_backlog/stories/US04-03-rename-apply.md

@@ -0,0 +1,24 @@
+# US04-03 — Apply and Verify Guarded Renames
+
+Epic: [E04](../E04-guarded-renaming.md)
+
+As a user, I want confirmed plans applied without overwrites so reorganizing the
+library preserves identity and bytes.
+
+## Acceptance criteria
+
+- Apply requires current plan/version confirmation and an exclusive mutation lease.
+- Preconditions are rechecked immediately before each mutation; unexpected targets
+  are never overwritten.
+- Case-only and cross-filesystem operations use safe staged procedures.
+- Postconditions verify bytes and paths, update occurrences, and reconcile stable IDs.
+
+## Automated tests
+
+- Filesystem integration tests cover normal, case-only, collision, cross-filesystem,
+  stale source, and repeated apply.
+- Tests assert byte preservation and database/path consistency after restart.
+
+## Dependencies
+
+- US04-02

delivery_backlog/stories/US04-04-rename-recovery.md

@@ -0,0 +1,23 @@
+# US04-04 — Recover or Roll Back Interrupted Renames
+
+Epic: [E04](../E04-guarded-renaming.md)
+
+As an operator, I want safe recovery choices after interruption so partially renamed
+albums never trigger blind retries or data loss.
+
+## Acceptance criteria
+
+- Recovery derives action from journal plus current source/destination evidence.
+- Resume and rollback revalidate recorded hashes and refuse changed paths.
+- Ambiguous states block unrelated mutations and explain manual recovery precisely.
+- Recovery and rollback are idempotent across repeated restarts.
+
+## Automated tests
+
+- Fault injection terminates the process at every persisted rename transition.
+- Tests cover resume, rollback, changed paths, unexpected destinations, and repeated
+  restart with no overwrite or asset loss.
+
+## Dependencies
+
+- US04-03

delivery_backlog/stories/US04-05-rename-ui.md

@@ -0,0 +1,22 @@
+# US04-05 — Operate Rename Plans in the Browser
+
+Epic: [E04](../E04-guarded-renaming.md)
+
+As a user, I want to preview, confirm, monitor, and recover renames in the browser so
+filesystem changes remain understandable and deliberate.
+
+## Acceptance criteria
+
+- Preview shows every affected path, validation issue, operation type, and count.
+- Confirmation includes the current server-issued plan/version token.
+- Progress, cancellation limits, terminal verification, and errors are visible.
+- Recovery blocks unrelated mutations and offers only evidence-safe actions.
+
+## Automated tests
+
+- UI/Playwright tests cover preview, stale confirmation, apply, progress, collision,
+  interruption, recovery, rollback, focus, and reload.
+
+## Dependencies
+
+- US04-03, US04-04

delivery_backlog/stories/US04-06-phase-d-e2e.md

@@ -0,0 +1,22 @@
+# US04-06 — Automate Phase D End-to-End Acceptance
+
+Epic: [E04](../E04-guarded-renaming.md)
+
+As a delivery owner, I want exhaustive automated rename journeys so every crash point
+and stale condition is proven safe.
+
+## Acceptance criteria
+
+- Journeys cover plan/export, confirmation, valid apply, case-only rename, collision,
+  stale source, cancellation boundary, every journal crash point, recovery, and rollback.
+- Stable IDs, hashes, asset set, journal, and UI state are asserted after restart.
+- Story IDs US04-01 through US04-05 map to passing automated tests.
+
+## Automated tests
+
+- One command runs API, filesystem fault-injection, and Playwright rename suites.
+- Phases A–C remain green and the source fixture corpus remains unchanged.
+
+## Dependencies
+
+- US04-01 through US04-05

delivery_backlog/stories/US05-01-upload-preflight.md

@@ -0,0 +1,23 @@
+# US05-01 — Validate Credentials and Upload Readiness
+
+Epic: [E05](../E05-immich-upload.md)
+
+As a user, I want upload blockers and scope validated before execution so unverified or
+changed files never reach Immich accidentally.
+
+## Acceptance criteria
+
+- Preflight checks credentials without exposing them, server reachability, selected
+  album scope, canonical/safety/analysis/EXIF readiness, and current byte hashes.
+- The redacted command preview shows exact folders, album mapping, and asset counts.
+- Partial scope and every blocker require explicit resolution or approved policy.
+- Preflight produces a versioned token invalidated by relevant changes.
+
+## Automated tests
+
+- Integration tests cover valid, missing/invalid credential, blocked stage, changed
+  bytes, partial album, stale token, and secret redaction.
+
+## Dependencies
+
+- E04 complete

delivery_backlog/stories/US05-02-upload-batches.md

@@ -0,0 +1,23 @@
+# US05-02 — Orchestrate Album Upload Batches
+
+Epic: [E05](../E05-immich-upload.md)
+
+As a user, I want one approved album uploaded at a time so scope, progress, and retries
+remain controlled.
+
+## Acceptance criteria
+
+- A durable upload batch records album, asset IDs, pre-upload hashes, command version,
+  attempts, progress, cancellation, and raw report location.
+- `immich-go` is invoked through the integration adapter with bounded output and no
+  shell interpolation or secret logging.
+- Only one configured uploader lane runs; restart resumes at safe item/batch boundaries.
+
+## Automated tests
+
+- Fake-executable integration tests verify arguments, album isolation, concurrency,
+  cancellation, restart, output limits, and credential privacy.
+
+## Dependencies
+
+- US05-01, US02-03

delivery_backlog/stories/US05-03-upload-reports.md

@@ -0,0 +1,22 @@
+# US05-03 — Parse and Persist Uploader Outcomes
+
+Epic: [E05](../E05-immich-upload.md)
+
+As an operator, I want uploader reports converted into durable typed outcomes so I can
+distinguish new, upgraded, duplicate, failed, and unknown assets.
+
+## Acceptance criteria
+
+- Version-specific parsers preserve bounded raw evidence and classify every item.
+- Unknown versions or lines never become success; they require verification.
+- Uploaded SHA-1/content evidence, timestamps, counts, and parser version are stored.
+- Reprocessing the same report is idempotent.
+
+## Automated tests
+
+- Golden parser fixtures cover every supported outcome/version and malformed output.
+- Repository tests cover idempotent import, count reconciliation, and restart.
+
+## Dependencies
+
+- US05-02

delivery_backlog/stories/US05-04-upload-verification.md

@@ -0,0 +1,22 @@
+# US05-04 — Verify, Retry, and Resolve Uncertain Uploads
+
+Epic: [E05](../E05-immich-upload.md)
+
+As a user, I want uncertain uploads verified before retry so a lost response cannot
+create duplicate server assets.
+
+## Acceptance criteria
+
+- Retry policy distinguishes safe failures from accepted-but-unknown outcomes.
+- Verification compares recorded local bytes with authoritative available evidence.
+- Changed-after-upload bytes create a visible stale warning and block unsafe actions.
+- Manual resolution records evidence and audit history; it never silently assumes success.
+
+## Automated tests
+
+- Fault tests cover timeout before acceptance, acceptance then lost response, parser
+  uncertainty, safe retry, changed bytes, and repeated verification.
+
+## Dependencies
+
+- US05-03

delivery_backlog/stories/US05-05-upload-ui.md

@@ -0,0 +1,23 @@
+# US05-05 — Operate Uploads in the Browser
+
+Epic: [E05](../E05-immich-upload.md)
+
+As a user, I want to preflight, confirm, monitor, and verify uploads so I know exactly
+what reached Immich and what remains uncertain.
+
+## Acceptance criteria
+
+- The view shows album scope, blockers, redacted configuration, counts, and exact
+  confirmation before start.
+- Progress distinguishes new, upgraded, duplicate, failed, cancelled, and uncertain.
+- Uncertain outcomes expose verification actions, not an automatic retry button.
+- Secrets never appear in DOM, logs, URLs, traces, or browser storage.
+
+## Automated tests
+
+- Playwright covers blocked/valid preflight, start, progress, cancellation, report,
+  uncertainty, verification, stale bytes, reload, and secret scanning.
+
+## Dependencies
+
+- US05-04

delivery_backlog/stories/US05-06-phase-e-e2e.md

@@ -0,0 +1,23 @@
+# US05-06 — Automate Phase E End-to-End Acceptance
+
+Epic: [E05](../E05-immich-upload.md)
+
+As a delivery owner, I want deterministic upload journeys so metadata ordering,
+deduplication outcomes, and uncertainty handling cannot regress.
+
+## Acceptance criteria
+
+- Journeys cover credential failure, preflight blockers, new, exact duplicate, upgrade,
+  retryable failure, acceptance-response loss, verification, cancellation, and resume.
+- Tests prove EXIF precedes upload and persisted hashes match submitted bytes.
+- No secret appears in retained artifacts; state is asserted after restart.
+- Story IDs US05-01 through US05-05 map to passing automated tests.
+
+## Automated tests
+
+- One command runs fake uploader, black-box API, and Playwright upload suites.
+- Phases A–D remain green.
+
+## Dependencies
+
+- US05-01 through US05-05

delivery_backlog/stories/US06-01-archive-preflight.md

@@ -0,0 +1,23 @@
+# US06-01 — Configure and Preflight Archive Destinations
+
+Epic: [E06](../E06-archive-lifecycle.md)
+
+As a user, I want archive destinations identified and validated so an album is never
+moved to the wrong, unavailable, or undersized storage.
+
+## Acceptance criteria
+
+- Archive locations record stable media/volume identity, root, capabilities, and state.
+- Preflight validates verified upload, current bytes, destination identity, capacity,
+  writability, boundaries, collisions, locks, backup, and manifest creation.
+- Preview shows transfer method, exact scope, reclaimable bytes, and every blocker.
+- Confirmation uses a versioned token invalidated by source/destination changes.
+
+## Automated tests
+
+- Integration tests cover valid, offline, wrong-volume, low-space, read-only, collision,
+  stale source, lock conflict, and unsafe path cases.
+
+## Dependencies
+
+- E05 complete

delivery_backlog/stories/US06-02-archive-transfer.md

@@ -0,0 +1,23 @@
+# US06-02 — Transfer, Verify, and Remove Active Sources
+
+Epic: [E06](../E06-archive-lifecycle.md)
+
+As a user, I want source files removed only after durable archive verification so
+reclaiming space cannot cause data loss.
+
+## Acceptance criteria
+
+- A journal records planned, transferring, verified, removing, and terminal item state.
+- Cross-filesystem flow copies to a temporary destination, closes, hashes, atomically
+  publishes, records manifest, then removes the matching source.
+- Same-filesystem optimization is used only when proven safe and still verified.
+- Unexpected source/destination changes stop the item without overwrite or deletion.
+
+## Automated tests
+
+- Filesystem/process tests interrupt every transition before and after source removal.
+- Tests assert manifest/hash correctness, idempotent recovery, and zero verified loss.
+
+## Dependencies
+
+- US06-01, US02-03

delivery_backlog/stories/US06-03-offline-assets.md

@@ -0,0 +1,22 @@
+# US06-03 — Preserve Offline Identity and Review Evidence
+
+Epic: [E06](../E06-archive-lifecycle.md)
+
+As a user, I want archived assets searchable and usable for deduplication while their
+media is offline so new copies are not mistaken for unrelated photos.
+
+## Acceptance criteria
+
+- Availability distinguishes active, archived online/offline, and unexpectedly missing.
+- Archived hashes remain in indexes and inventory scans do not prune offline assets.
+- Protected comparison previews and evidence remain available under a durable policy.
+- Exact and fuzzy active matches link to archived canonicals with appropriate review.
+
+## Automated tests
+
+- Integration tests toggle fake mounts, rescan, discover exact/fuzzy copies, review
+  previews, and assert stable state across restart.
+
+## Dependencies
+
+- US06-02

delivery_backlog/stories/US06-04-restore.md

@@ -0,0 +1,24 @@
+# US06-04 — Plan and Execute Safe Restores
+
+Epic: [E06](../E06-archive-lifecycle.md)
+
+As a user, I want archived assets restored to collision-free active paths so I can
+recover originals without losing identity or previous decisions.
+
+## Acceptance criteria
+
+- Restore preflight requires the correct archive identity, matching bytes, capacity,
+  safe destination, and no conflicting lease.
+- Restore copies, closes, verifies, atomically publishes, and registers an active
+  occurrence while preserving asset identity and stage history.
+- Collisions never overwrite; mismatches become stale/divergent states.
+- Restore is journaled, resumable, and idempotent.
+
+## Automated tests
+
+- Tests cover offline media, wrong volume, normal restore, collision, changed archive
+  bytes, interruption, repeated restart, and preserved decisions.
+
+## Dependencies
+
+- US06-03

delivery_backlog/stories/US06-05-archive-ui.md

@@ -0,0 +1,23 @@
+# US06-05 — Operate Archive and Restore in the Browser
+
+Epic: [E06](../E06-archive-lifecycle.md)
+
+As a user, I want to preview, confirm, monitor, recover, and restore archives so storage
+reclamation remains understandable and reversible.
+
+## Acceptance criteria
+
+- Archive preview shows exact scope, destination identity, transfer method, capacity,
+  blockers, and reclaimable bytes.
+- Progress separates transfer, verification, and source-removal states.
+- Offline assets remain browsable with clear availability and mount instructions.
+- Recovery and restore views expose only safe evidence-backed actions.
+
+## Automated tests
+
+- Playwright covers preflight blockers, confirmation, progress, interruption/recovery,
+  offline browsing, restore, collision, keyboard operation, and reload.
+
+## Dependencies
+
+- US06-02, US06-03, US06-04

delivery_backlog/stories/US06-06-phase-f-e2e.md

@@ -0,0 +1,23 @@
+# US06-06 — Automate Phase F End-to-End Acceptance
+
+Epic: [E06](../E06-archive-lifecycle.md)
+
+As a delivery owner, I want archive lifecycle automation so removal, offline behavior,
+recovery, and restore are proven without risking real files.
+
+## Acceptance criteria
+
+- Journeys cover preflight blockers, copy/verify/remove, same-filesystem behavior,
+  every interruption point, offline deduplication, mount return, restore, and collision.
+- API, journal, manifest, paths, hashes, previews, and durable state are asserted after
+  restart; no source is removed before archive verification.
+- Story IDs US06-01 through US06-05 map to passing automated tests.
+
+## Automated tests
+
+- One command runs archive fault-injection, black-box API, and Playwright suites.
+- Phases A–E remain green.
+
+## Dependencies
+
+- US06-01 through US06-05

delivery_backlog/stories/US07-01-donor-archive.md

@@ -0,0 +1,24 @@
+# US07-01 — Complete Donor Migration and Freeze the CLI Archive
+
+Epic: [E07](../E07-hardening-release.md)
+
+As a maintainer, I want all useful legacy behavior resolved and original CLIs frozen
+with provenance so production has one implementation without losing historical evidence.
+
+## Acceptance criteria
+
+- Every in-scope donor-ledger row has a target, characterization test, parity result,
+  and documented intentional delta where applicable.
+- Remaining CSV state is migrated and reconciled into SQLite with a report.
+- Original sources, docs, dependency lock, schema/config notes, version, and checksums
+  are placed in the read-only legacy archive with secrets removed.
+- Production imports and runtime paths cannot load or execute archived scripts.
+
+## Automated tests
+
+- Ledger/archive lint verifies completeness, checksums, redaction, and non-importability.
+- Full parity and database migration/reconciliation suites pass.
+
+## Dependencies
+
+- E01–E06 complete

delivery_backlog/stories/US07-02-security-hardening.md

@@ -0,0 +1,23 @@
+# US07-02 — Harden API Authorization and Path Boundaries
+
+Epic: [E07](../E07-hardening-release.md)
+
+As an operator, I want the local application resistant to cross-origin and path attacks
+so another process or webpage cannot access photos or trigger mutations.
+
+## Acceptance criteria
+
+- Session authentication, Origin/Host checks, SameSite cookies, CSRF protection, and
+  restrictive CORS/default headers cover all mutation and media endpoints.
+- Asset IDs, repeated root validation, symlink defense, upload limits, and schema
+  validation prevent raw-path and race escapes.
+- Errors reveal no secrets, filesystem internals, or private metadata unnecessarily.
+
+## Automated tests
+
+- Black-box security tests cover missing/invalid auth, CSRF, hostile origins/hosts,
+  traversal, symlink races, malformed/oversized requests, and information leakage.
+
+## Dependencies
+
+- US07-01

delivery_backlog/stories/US07-03-media-hardening.md

@@ -0,0 +1,24 @@
+# US07-03 — Harden Media and Metadata Edge Cases
+
+Epic: [E07](../E07-hardening-release.md)
+
+As a user, I want unusual or damaged media handled safely so one file cannot corrupt
+metadata, exhaust resources, or stop the library workflow.
+
+## Acceptance criteria
+
+- Supported format/orientation/profile combinations have bounded decode behavior.
+- Corrupt, truncated, huge-dimension, unsupported, and malformed-metadata files become
+  precise item errors without worker failure.
+- EXIF checkpoints preserve user fields and previous-stage fields, read back owned
+  fields, and mark conflicts divergent rather than silently repairing them.
+- Cache regeneration/invalidation and temporary-file cleanup are safe and scoped.
+
+## Automated tests
+
+- Extended golden corpus covers all declared format, orientation, corruption, and EXIF
+  cases with memory/time bounds and before/after metadata snapshots.
+
+## Dependencies
+
+- US07-01

delivery_backlog/stories/US07-04-fault-concurrency.md

@@ -0,0 +1,25 @@
+# US07-04 — Prove Concurrency and Crash Recovery
+
+Epic: [E07](../E07-hardening-release.md)
+
+As an operator, I want randomized race and fault tests so concurrency cannot produce
+deadlocks, stale commits, duplicate terminal states, or data loss.
+
+## Acceptance criteria
+
+- Test control points exist at persisted transitions without exposing production
+  mutation APIs.
+- Tests cover database pressure, worker claim races, file changes, thumbnail races,
+  safety/analysis races, EXIF/upload races, rename/archive conflicts, and cancellation.
+- Faults cover process death, disk full, read-only paths, DB busy/corruption, network
+  failures, malformed providers, GPU exhaustion, subprocess hangs, and missing tools.
+- Recovery is deterministic or enters an explicit manual-recovery state.
+
+## Automated tests
+
+- Randomized suites repeat with recorded seeds and assert invariants after restart.
+- CI retains journals, logs, DB, seed, and filesystem manifest for any failure.
+
+## Dependencies
+
+- US07-02, US07-03

delivery_backlog/stories/US07-05-backup-operations.md

@@ -0,0 +1,24 @@
+# US07-05 — Deliver Backup and Operational Recovery
+
+Epic: [E07](../E07-hardening-release.md)
+
+As an operator, I want documented and tested backup/recovery procedures so application
+state can be restored after migration failure, database damage, or storage loss.
+
+## Acceptance criteria
+
+- Online backup includes database consistency, required manifests, configuration
+  references, and retention guidance without copying secrets into logs.
+- Integrity checks, migration rollback/recovery, archive media handling, and restore
+  drills have step-by-step documentation.
+- Operational diagnostics report DB/WAL/cache/log/thumbnail sizes and low-disk risks.
+- Legacy-process locking prevents incompatible simultaneous mutations.
+
+## Automated tests
+
+- Recovery drills restore backups into fresh roots and run integrity/reconciliation.
+- Tests cover failed migration, corrupt copy detection, retention, and process locking.
+
+## Dependencies
+
+- US07-01, US07-04

delivery_backlog/stories/US07-06-performance.md

@@ -0,0 +1,24 @@
+# US07-06 — Validate Performance and Resource Bounds
+
+Epic: [E07](../E07-hardening-release.md)
+
+As an operator, I want measured performance and bounded resource use so large libraries
+remain responsive and do not exhaust memory, disk, handles, or queues.
+
+## Acceptance criteria
+
+- Agreed budgets cover API latency, throughput, RSS, open files, WAL, queues, cache,
+  disk reserve, and event delivery at 25k, 100k, and 500k synthetic assets.
+- Duplicate clusters with thousands of members remain usable and paged.
+- Multi-hour work plus browsing, cancellation, retry, backup, and cache eviction shows
+  no unbounded growth or starvation.
+- Budget exceptions are measured, documented, and approved before release.
+
+## Automated tests
+
+- Repeatable load/soak commands export machine-readable metrics and fail budget breaches.
+- CI runs a short profile; scheduled infrastructure runs the full soak matrix.
+
+## Dependencies
+
+- US07-04, US07-05

delivery_backlog/stories/US07-07-release-e2e.md

@@ -0,0 +1,29 @@
+# US07-07 — Automate Full Release Acceptance
+
+Epic: [E07](../E07-hardening-release.md)
+
+As a release owner, I want one reproducible automated release gate so every user story
+and complete workflow is proven before real-library mutation is enabled.
+
+## Acceptance criteria
+
+- A story-to-test matrix contains every backlog story with no missing, skipped, or
+  failing required test.
+- One fresh-environment journey runs discovery, duplicate review, safety, analysis,
+  EXIF verification, album proposal, rename, rescan, upload, archive, offline
+  deduplication, restore, and full process restarts.
+- Security, migration, donor parity, crash recovery, accessibility, responsive UI,
+  browser console/network, fixture reproducibility, and archive safety gates pass.
+- A read-only real-library dry run produces an explicitly approved reconciliation
+  report before mutation can be configured.
+
+## Automated tests
+
+- One documented release command provisions and destroys the full isolated stack and
+  retains signed/versioned evidence.
+- Chromium passes every change; supported cross-browser and full soak suites pass for
+  release; all earlier epic suites run unchanged.
+
+## Dependencies
+
+- US07-01 through US07-06