elspais 0.9.3__py3-none-any.whl → 0.11.1__py3-none-any.whl

elspais/trace_view/review/storage.py

@@ -0,0 +1,1367 @@
+#!/usr/bin/env python3
+"""
+Review Storage Operations Module for trace_view
+
+CRUD operations for the review system:
+- Config operations (load/save)
+- Review flag operations (load/save)
+- Thread operations (load/save/add/resolve/unresolve)
+- Status request operations (load/save/create/approve/apply)
+- Package operations (load/save/create/update/delete)
+- Merge operations for combining multiple user branches
+
+IMPLEMENTS REQUIREMENTS:
+    REQ-tv-d00011: Review Storage Operations
+"""
+
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .models import (
+    ReviewConfig,
+    ReviewFlag,
+    Thread,
+    Comment,
+    ThreadsFile,
+    StatusFile,
+    StatusRequest,
+    Approval,
+    ReviewPackage,
+    PackagesFile,
+    parse_iso_datetime,
+)
+
+
+# =============================================================================
+# Helper Functions
+# REQ-tv-d00011-A: Atomic write operations
+# =============================================================================
+
+def atomic_write_json(path: Path, data: Dict[str, Any]) -> None:
+    """
+    Atomically write JSON data to a file.
+
+    REQ-tv-d00011-A: Uses temp file + rename pattern to ensure file is either
+    fully written or not changed at all.
+
+    Args:
+        path: Target file path
+        data: JSON-serializable dictionary
+    """
+    # Ensure parent directories exist
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write to temp file in same directory (for atomic rename)
+    fd, temp_path = tempfile.mkstemp(
+        suffix='.json',
+        prefix='.tmp_',
+        dir=path.parent
+    )
+    try:
+        with os.fdopen(fd, 'w') as f:
+            json.dump(data, f, indent=2)
+        # Atomic rename
+        os.rename(temp_path, path)
+    except Exception:
+        # Clean up temp file on failure
+        if os.path.exists(temp_path):
+            os.unlink(temp_path)
+        raise
+
+
+def read_json(path: Path) -> Dict[str, Any]:
+    """
+    Read JSON file and return dictionary.
+
+    Args:
+        path: Path to JSON file
+
+    Returns:
+        Parsed JSON as dictionary
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        json.JSONDecodeError: If file contains invalid JSON
+    """
+    with open(path, 'r') as f:
+        return json.load(f)
+
+
+# =============================================================================
+# Path Functions
+# REQ-tv-d00011-H: Storage paths convention
+# REQ-tv-d00011-I: Requirement ID normalization
+# =============================================================================
+
+def normalize_req_id(req_id: str) -> str:
+    """
+    Normalize requirement ID for use in file paths.
+
+    REQ-tv-d00011-I: Replace colons and slashes with underscores.
+
+    Args:
+        req_id: Original requirement ID
+
+    Returns:
+        Normalized requirement ID safe for file paths
+    """
+    return re.sub(r'[:/]', '_', req_id)
+
+
+def get_reviews_root(repo_root: Path) -> Path:
+    """
+    Get the root directory for review storage.
+
+    REQ-tv-d00011-H: Returns .reviews directory.
+
+    Args:
+        repo_root: Repository root path
+
+    Returns:
+        Path to .reviews directory
+    """
+    return repo_root / '.reviews'
+
+
+def get_req_dir(repo_root: Path, req_id: str) -> Path:
+    """
+    Get the directory for a specific requirement's review data.
+
+    REQ-tv-d00011-H: Returns .reviews/reqs/{normalized-req-id}/
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+
+    Returns:
+        Path to requirement's review directory
+    """
+    normalized = normalize_req_id(req_id)
+    return get_reviews_root(repo_root) / 'reqs' / normalized
+
+
+def get_threads_path(repo_root: Path, req_id: str) -> Path:
+    """
+    Get path to threads.json file for a requirement.
+
+    REQ-tv-d00011-H: Returns .reviews/reqs/{normalized-req-id}/threads.json
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+
+    Returns:
+        Path to threads.json
+    """
+    return get_req_dir(repo_root, req_id) / 'threads.json'
+
+
+def get_status_path(repo_root: Path, req_id: str) -> Path:
+    """
+    Get path to status.json file for a requirement.
+
+    REQ-tv-d00011-H: Returns .reviews/reqs/{normalized-req-id}/status.json
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+
+    Returns:
+        Path to status.json
+    """
+    return get_req_dir(repo_root, req_id) / 'status.json'
+
+
+def get_review_flag_path(repo_root: Path, req_id: str) -> Path:
+    """
+    Get path to flag.json file for a requirement.
+
+    REQ-tv-d00011-H: Returns .reviews/reqs/{normalized-req-id}/flag.json
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+
+    Returns:
+        Path to flag.json
+    """
+    return get_req_dir(repo_root, req_id) / 'flag.json'
+
+
+def get_config_path(repo_root: Path) -> Path:
+    """
+    Get path to config.json file.
+
+    REQ-tv-d00011-H: Returns .reviews/config.json
+
+    Args:
+        repo_root: Repository root path
+
+    Returns:
+        Path to config.json
+    """
+    return get_reviews_root(repo_root) / 'config.json'
+
+
+def get_packages_path(repo_root: Path) -> Path:
+    """
+    Get path to packages.json file (v1 format).
+
+    REQ-tv-d00011-H: Returns .reviews/packages.json
+
+    Args:
+        repo_root: Repository root path
+
+    Returns:
+        Path to packages.json
+    """
+    return get_reviews_root(repo_root) / 'packages.json'
+
+
+# =============================================================================
+# V2 Path Functions (Package-Centric Storage)
+# REQ-d00096: Review Storage Architecture
+# =============================================================================
+
+def get_index_path(repo_root: Path) -> Path:
+    """
+    Get path to index.json file (v2 format).
+
+    REQ-d00096-D: Returns .reviews/index.json
+
+    Args:
+        repo_root: Repository root path
+
+    Returns:
+        Path to index.json
+    """
+    return get_reviews_root(repo_root) / 'index.json'
+
+
+def get_package_dir(repo_root: Path, package_id: str) -> Path:
+    """
+    Get the directory for a specific package (v2 format).
+
+    REQ-d00096-A: Returns .reviews/packages/{pkg-id}/
+
+    Args:
+        repo_root: Repository root path
+        package_id: Package UUID
+
+    Returns:
+        Path to package directory
+    """
+    return get_reviews_root(repo_root) / 'packages' / package_id
+
+
+def get_package_metadata_path(repo_root: Path, package_id: str) -> Path:
+    """
+    Get path to package.json file for a package (v2 format).
+
+    REQ-d00096-B: Returns .reviews/packages/{pkg-id}/package.json
+
+    Args:
+        repo_root: Repository root path
+        package_id: Package UUID
+
+    Returns:
+        Path to package.json
+    """
+    return get_package_dir(repo_root, package_id) / 'package.json'
+
+
+def get_package_threads_path(repo_root: Path, package_id: str, req_id: str) -> Path:
+    """
+    Get path to threads.json file for a requirement within a package (v2 format).
+
+    REQ-d00096-C: Returns .reviews/packages/{pkg-id}/reqs/{req-id}/threads.json
+
+    Args:
+        repo_root: Repository root path
+        package_id: Package UUID
+        req_id: Requirement ID
+
+    Returns:
+        Path to threads.json
+    """
+    normalized = normalize_req_id(req_id)
+    return get_package_dir(repo_root, package_id) / 'reqs' / normalized / 'threads.json'
+
+
+def get_archive_dir(repo_root: Path) -> Path:
+    """
+    Get the root directory for archived packages.
+
+    REQ-d00097-A: Returns .reviews/archive/
+
+    Args:
+        repo_root: Repository root path
+
+    Returns:
+        Path to archive directory
+    """
+    return get_reviews_root(repo_root) / 'archive'
+
+
+def get_archived_package_dir(repo_root: Path, package_id: str) -> Path:
+    """
+    Get the directory for an archived package.
+
+    REQ-d00097-A: Returns .reviews/archive/{pkg-id}/
+
+    Args:
+        repo_root: Repository root path
+        package_id: Package UUID
+
+    Returns:
+        Path to archived package directory
+    """
+    return get_archive_dir(repo_root) / package_id
+
+
+def get_archived_package_metadata_path(repo_root: Path, package_id: str) -> Path:
+    """
+    Get path to package.json file for an archived package.
+
+    REQ-d00097-B: Returns .reviews/archive/{pkg-id}/package.json
+
+    Args:
+        repo_root: Repository root path
+        package_id: Package UUID
+
+    Returns:
+        Path to archived package.json
+    """
+    return get_archived_package_dir(repo_root, package_id) / 'package.json'
+
+
+def get_archived_package_threads_path(
+    repo_root: Path,
+    package_id: str,
+    req_id: str
+) -> Path:
+    """
+    Get path to threads.json file for a requirement within an archived package.
+
+    REQ-d00097-B: Returns .reviews/archive/{pkg-id}/reqs/{req-id}/threads.json
+
+    Args:
+        repo_root: Repository root path
+        package_id: Package UUID
+        req_id: Requirement ID
+
+    Returns:
+        Path to archived threads.json
+    """
+    normalized = normalize_req_id(req_id)
+    return get_archived_package_dir(repo_root, package_id) / 'reqs' / normalized / 'threads.json'
+
+
+# =============================================================================
+# Config Operations
+# REQ-tv-d00011-F: Config storage operations
+# =============================================================================
+
+def load_config(repo_root: Path) -> ReviewConfig:
+    """
+    Load review system configuration.
+
+    REQ-tv-d00011-F: Returns default config if file doesn't exist.
+
+    Args:
+        repo_root: Repository root path
+
+    Returns:
+        ReviewConfig instance
+    """
+    config_path = get_config_path(repo_root)
+    if not config_path.exists():
+        return ReviewConfig.default()
+    data = read_json(config_path)
+    return ReviewConfig.from_dict(data)
+
+
+def save_config(repo_root: Path, config: ReviewConfig) -> None:
+    """
+    Save review system configuration.
+
+    REQ-tv-d00011-F: Uses atomic write for safety.
+
+    Args:
+        repo_root: Repository root path
+        config: ReviewConfig instance to save
+    """
+    config_path = get_config_path(repo_root)
+    atomic_write_json(config_path, config.to_dict())
+
+
+# =============================================================================
+# Review Flag Operations
+# REQ-tv-d00011-D: Review flag storage operations
+# =============================================================================
+
+def load_review_flag(repo_root: Path, req_id: str) -> ReviewFlag:
+    """
+    Load review flag for a requirement.
+
+    REQ-tv-d00011-D: Returns cleared flag if file doesn't exist.
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+
+    Returns:
+        ReviewFlag instance
+    """
+    flag_path = get_review_flag_path(repo_root, req_id)
+    if not flag_path.exists():
+        return ReviewFlag.cleared()
+    data = read_json(flag_path)
+    return ReviewFlag.from_dict(data)
+
+
+def save_review_flag(repo_root: Path, req_id: str, flag: ReviewFlag) -> None:
+    """
+    Save review flag for a requirement.
+
+    REQ-tv-d00011-D: Uses atomic write for safety.
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+        flag: ReviewFlag instance to save
+    """
+    flag_path = get_review_flag_path(repo_root, req_id)
+    atomic_write_json(flag_path, flag.to_dict())
+
+
+# =============================================================================
+# Thread Operations
+# REQ-tv-d00011-B: Thread storage operations
+# =============================================================================
+
+def load_threads(repo_root: Path, req_id: str) -> ThreadsFile:
+    """
+    Load threads for a requirement.
+
+    REQ-tv-d00011-B: Returns empty threads file if doesn't exist.
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+
+    Returns:
+        ThreadsFile instance
+    """
+    normalized_id = normalize_req_id(req_id)
+    threads_path = get_threads_path(repo_root, req_id)
+    if not threads_path.exists():
+        return ThreadsFile(reqId=normalized_id, threads=[])
+    data = read_json(threads_path)
+    return ThreadsFile.from_dict(data)
+
+
+def save_threads(repo_root: Path, req_id: str, threads_file: ThreadsFile) -> None:
+    """
+    Save threads file for a requirement.
+
+    REQ-tv-d00011-B: Uses atomic write for safety.
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+        threads_file: ThreadsFile instance to save
+    """
+    threads_path = get_threads_path(repo_root, req_id)
+    atomic_write_json(threads_path, threads_file.to_dict())
+
+
+def add_thread(repo_root: Path, req_id: str, thread: Thread) -> Thread:
+    """
+    Add a new thread to a requirement.
+
+    REQ-tv-d00011-B: Creates file if needed and appends thread.
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+        thread: Thread to add
+
+    Returns:
+        The added thread
+    """
+    threads_file = load_threads(repo_root, req_id)
+    threads_file.threads.append(thread)
+    save_threads(repo_root, req_id, threads_file)
+    return thread
+
+
+def add_comment_to_thread(
+    repo_root: Path,
+    req_id: str,
+    thread_id: str,
+    author: str,
+    body: str
+) -> Comment:
+    """
+    Add a comment to an existing thread.
+
+    REQ-tv-d00011-B: Persists comment and returns it.
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+        thread_id: Thread UUID
+        author: Comment author username
+        body: Comment body text
+
+    Returns:
+        The created comment
+
+    Raises:
+        ValueError: If thread not found
+    """
+    threads_file = load_threads(repo_root, req_id)
+
+    # Find the thread
+    thread = None
+    for t in threads_file.threads:
+        if t.threadId == thread_id:
+            thread = t
+            break
+
+    if thread is None:
+        raise ValueError(f"Thread not found: {thread_id}")
+
+    comment = thread.add_comment(author, body)
+    save_threads(repo_root, req_id, threads_file)
+    return comment
+
+
+def resolve_thread(
+    repo_root: Path,
+    req_id: str,
+    thread_id: str,
+    user: str
+) -> bool:
+    """
+    Mark a thread as resolved.
+
+    REQ-tv-d00011-B: Persists resolution state.
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+        thread_id: Thread UUID
+        user: Username resolving the thread
+
+    Returns:
+        True if resolved, False if thread not found
+    """
+    threads_file = load_threads(repo_root, req_id)
+
+    for thread in threads_file.threads:
+        if thread.threadId == thread_id:
+            thread.resolve(user)
+            save_threads(repo_root, req_id, threads_file)
+            return True
+
+    return False
+
+
+def unresolve_thread(repo_root: Path, req_id: str, thread_id: str) -> bool:
+    """
+    Mark a thread as unresolved.
+
+    REQ-tv-d00011-B: Persists unresolved state.
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+        thread_id: Thread UUID
+
+    Returns:
+        True if unresolved, False if thread not found
+    """
+    threads_file = load_threads(repo_root, req_id)
+
+    for thread in threads_file.threads:
+        if thread.threadId == thread_id:
+            thread.unresolve()
+            save_threads(repo_root, req_id, threads_file)
+            return True
+
+    return False
+
+
+# =============================================================================
+# Status Request Operations
+# REQ-tv-d00011-C: Status request storage operations
+# =============================================================================
+
+def load_status_requests(repo_root: Path, req_id: str) -> StatusFile:
+    """
+    Load status requests for a requirement.
+
+    REQ-tv-d00011-C: Returns empty status file if doesn't exist.
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+
+    Returns:
+        StatusFile instance
+    """
+    normalized_id = normalize_req_id(req_id)
+    status_path = get_status_path(repo_root, req_id)
+    if not status_path.exists():
+        return StatusFile(reqId=normalized_id, requests=[])
+    data = read_json(status_path)
+    return StatusFile.from_dict(data)
+
+
+def save_status_requests(repo_root: Path, req_id: str, status_file: StatusFile) -> None:
+    """
+    Save status requests file for a requirement.
+
+    REQ-tv-d00011-C: Uses atomic write for safety.
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+        status_file: StatusFile instance to save
+    """
+    status_path = get_status_path(repo_root, req_id)
+    atomic_write_json(status_path, status_file.to_dict())
+
+
+def create_status_request(
+    repo_root: Path,
+    req_id: str,
+    request: StatusRequest
+) -> StatusRequest:
+    """
+    Create a new status change request.
+
+    REQ-tv-d00011-C: Persists request and returns it.
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+        request: StatusRequest to create
+
+    Returns:
+        The created request
+    """
+    status_file = load_status_requests(repo_root, req_id)
+    status_file.requests.append(request)
+    save_status_requests(repo_root, req_id, status_file)
+    return request
+
+
+def add_approval(
+    repo_root: Path,
+    req_id: str,
+    request_id: str,
+    user: str,
+    decision: str,
+    comment: Optional[str] = None
+) -> Approval:
+    """
+    Add an approval to a status request.
+
+    REQ-tv-d00011-C: Persists approval and returns it.
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+        request_id: Request UUID
+        user: Approving user
+        decision: "approve" or "reject"
+        comment: Optional comment
+
+    Returns:
+        The created approval
+
+    Raises:
+        ValueError: If request not found
+    """
+    status_file = load_status_requests(repo_root, req_id)
+
+    # Find the request
+    request = None
+    for r in status_file.requests:
+        if r.requestId == request_id:
+            request = r
+            break
+
+    if request is None:
+        raise ValueError(f"Status request not found: {request_id}")
+
+    approval = request.add_approval(user, decision, comment)
+    save_status_requests(repo_root, req_id, status_file)
+    return approval
+
+
+def mark_request_applied(repo_root: Path, req_id: str, request_id: str) -> bool:
+    """
+    Mark a status request as applied.
+
+    REQ-tv-d00011-C: Persists applied state.
+
+    Args:
+        repo_root: Repository root path
+        req_id: Requirement ID
+        request_id: Request UUID
+
+    Returns:
+        True if marked applied, False if not found
+
+    Raises:
+        ValueError: If request is not in approved state
+    """
+    status_file = load_status_requests(repo_root, req_id)
+
+    for request in status_file.requests:
+        if request.requestId == request_id:
+            request.mark_applied()  # This raises ValueError if not approved
+            save_status_requests(repo_root, req_id, status_file)
+            return True
+
+    return False
+
+
+# =============================================================================
+# Package Operations
+# REQ-tv-d00011-E: Package storage operations
+# =============================================================================
+
+def load_packages(repo_root: Path) -> PackagesFile:
+    """
+    Load packages file.
+
+    REQ-tv-d00011-E: Returns file with default package if doesn't exist.
+
+    Args:
+        repo_root: Repository root path
+
+    Returns:
+        PackagesFile instance
+    """
+    packages_path = get_packages_path(repo_root)
+    if not packages_path.exists():
+        # Create default package
+        default_pkg = ReviewPackage.create_default()
+        return PackagesFile(packages=[default_pkg])
+    data = read_json(packages_path)
+    packages_file = PackagesFile.from_dict(data)
+
+    # Ensure default package exists
+    if packages_file.get_default() is None:
+        default_pkg = ReviewPackage.create_default()
+        packages_file.packages.insert(0, default_pkg)
+
+    return packages_file
+
+
+def save_packages(repo_root: Path, packages_file: PackagesFile) -> None:
+    """
+    Save packages file.
+
+    REQ-tv-d00011-E: Uses atomic write for safety.
+
+    Args:
+        repo_root: Repository root path
+        packages_file: PackagesFile instance to save
+    """
+    packages_path = get_packages_path(repo_root)
+    atomic_write_json(packages_path, packages_file.to_dict())
+
+
+def create_package(repo_root: Path, package: ReviewPackage) -> ReviewPackage:
+    """
+    Create a new package.
+
+    REQ-tv-d00011-E: Persists package and returns it.
+
+    Args:
+        repo_root: Repository root path
+        package: ReviewPackage to create
+
+    Returns:
+        The created package
+    """
+    packages_file = load_packages(repo_root)
+    packages_file.packages.append(package)
+    save_packages(repo_root, packages_file)
+    return package
+
+
+def update_package(repo_root: Path, package: ReviewPackage) -> bool:
+    """
+    Update an existing package.
+
+    REQ-tv-d00011-E: Persists updated package.
+
+    Args:
+        repo_root: Repository root path
+        package: ReviewPackage with updated data
+
+    Returns:
+        True if updated, False if package not found
+    """
+    packages_file = load_packages(repo_root)
+
+    for i, p in enumerate(packages_file.packages):
+        if p.packageId == package.packageId:
+            packages_file.packages[i] = package
+            save_packages(repo_root, packages_file)
+            return True
+
+    return False
+
+
+def delete_package(repo_root: Path, package_id: str) -> bool:
+    """
+    Delete a package by ID.
+
+    REQ-tv-d00011-E: Removes package and persists change.
+
+    Args:
+        repo_root: Repository root path
+        package_id: Package UUID
+
+    Returns:
+        True if deleted, False if package not found
+    """
+    packages_file = load_packages(repo_root)
+
+    for i, p in enumerate(packages_file.packages):
+        if p.packageId == package_id:
+            del packages_file.packages[i]
+            save_packages(repo_root, packages_file)
+            return True
+
+    return False
+
+
+def add_req_to_package(repo_root: Path, package_id: str, req_id: str) -> bool:
+    """
+    Add a requirement ID to a package.
+
+    REQ-tv-d00011-E: Prevents duplicates.
+
+    Args:
+        repo_root: Repository root path
+        package_id: Package UUID
+        req_id: Requirement ID to add
+
+    Returns:
+        True if added, False if package not found
+    """
+    packages_file = load_packages(repo_root)
+
+    for package in packages_file.packages:
+        if package.packageId == package_id:
+            if req_id not in package.reqIds:
+                package.reqIds.append(req_id)
+            save_packages(repo_root, packages_file)
+            return True
+
+    return False
+
+
+def remove_req_from_package(repo_root: Path, package_id: str, req_id: str) -> bool:
+    """
+    Remove a requirement ID from a package.
+
+    REQ-tv-d00011-E: Persists change.
+
+    Args:
+        repo_root: Repository root path
+        package_id: Package UUID
+        req_id: Requirement ID to remove
+
+    Returns:
+        True if removed, False if package not found
+    """
+    packages_file = load_packages(repo_root)
+
+    for package in packages_file.packages:
+        if package.packageId == package_id:
+            if req_id in package.reqIds:
+                package.reqIds.remove(req_id)
+            save_packages(repo_root, packages_file)
+            return True
+
+    return False
+
+
+# =============================================================================
+# Merge Operations
+# REQ-tv-d00011-G: Merge operations
+# REQ-tv-d00011-J: Deduplication and timestamp-based conflict resolution
+# =============================================================================
+
+def merge_threads(local: ThreadsFile, remote: ThreadsFile) -> ThreadsFile:
+    """
+    Merge thread files from local and remote.
+
+    REQ-tv-d00011-G: Combines data from multiple user branches.
+    REQ-tv-d00011-J: Deduplicates by ID and uses timestamp-based conflict resolution.
+
+    Strategy:
+    - Unique threads (by threadId) are combined
+    - Matching threads merge their comments (by comment id)
+    - Resolution state: if either is resolved, keep resolved
+
+    Args:
+        local: Local threads file
+        remote: Remote threads file
+
+    Returns:
+        Merged ThreadsFile
+    """
+    # Build map of local threads by ID
+    local_map: Dict[str, Thread] = {t.threadId: t for t in local.threads}
+
+    merged_threads: List[Thread] = []
+
+    # Process all remote threads
+    for remote_thread in remote.threads:
+        if remote_thread.threadId in local_map:
+            # Merge the threads
+            local_thread = local_map.pop(remote_thread.threadId)
+            merged_thread = _merge_single_thread(local_thread, remote_thread)
+            merged_threads.append(merged_thread)
+        else:
+            # Only in remote
+            merged_threads.append(remote_thread)
+
+    # Add remaining local-only threads
+    for local_thread in local_map.values():
+        merged_threads.append(local_thread)
+
+    return ThreadsFile(reqId=local.reqId, threads=merged_threads)
+
+
+def _merge_single_thread(local: Thread, remote: Thread) -> Thread:
+    """
+    Merge two versions of the same thread.
+
+    REQ-tv-d00011-J: Deduplicates comments by ID and sorts by timestamp.
+    """
+    # Merge comments by ID
+    local_comment_map = {c.id: c for c in local.comments}
+    remote_comment_map = {c.id: c for c in remote.comments}
+
+    all_comment_ids = set(local_comment_map.keys()) | set(remote_comment_map.keys())
+    merged_comments = []
+
+    for comment_id in all_comment_ids:
+        if comment_id in local_comment_map:
+            merged_comments.append(local_comment_map[comment_id])
+        else:
+            merged_comments.append(remote_comment_map[comment_id])
+
+    # Sort comments by timestamp
+    merged_comments.sort(key=lambda c: parse_iso_datetime(c.timestamp))
+
+    # Resolution: if either resolved, keep resolved (prefer whichever has the state)
+    resolved = local.resolved or remote.resolved
+    resolved_by = remote.resolvedBy if remote.resolved else local.resolvedBy
+    resolved_at = remote.resolvedAt if remote.resolved else local.resolvedAt
+
+    return Thread(
+        threadId=local.threadId,
+        reqId=local.reqId,
+        createdBy=local.createdBy,
+        createdAt=local.createdAt,
+        position=local.position,  # Use local position
+        resolved=resolved,
+        resolvedBy=resolved_by,
+        resolvedAt=resolved_at,
+        comments=merged_comments
+    )
+
+
+def merge_status_files(local: StatusFile, remote: StatusFile) -> StatusFile:
+    """
+    Merge status files from local and remote.
+
+    REQ-tv-d00011-G: Combines data from multiple user branches.
+    REQ-tv-d00011-J: Deduplicates by ID and uses timestamp-based conflict resolution.
+
+    Strategy:
+    - Unique requests (by requestId) are combined
+    - Matching requests merge their approvals
+    - State is recalculated based on merged approvals
+
+    Args:
+        local: Local status file
+        remote: Remote status file
+
+    Returns:
+        Merged StatusFile
+    """
+    # Build map of local requests by ID
+    local_map: Dict[str, StatusRequest] = {r.requestId: r for r in local.requests}
+
+    merged_requests: List[StatusRequest] = []
+
+    # Process all remote requests
+    for remote_request in remote.requests:
+        if remote_request.requestId in local_map:
+            # Merge the requests
+            local_request = local_map.pop(remote_request.requestId)
+            merged_request = _merge_single_request(local_request, remote_request)
+            merged_requests.append(merged_request)
+        else:
+            # Only in remote
+            merged_requests.append(remote_request)
+
+    # Add remaining local-only requests
+    for local_request in local_map.values():
+        merged_requests.append(local_request)
+
+    return StatusFile(reqId=local.reqId, requests=merged_requests)
+
+
+def _merge_single_request(local: StatusRequest, remote: StatusRequest) -> StatusRequest:
+    """
+    Merge two versions of the same status request.
+
+    REQ-tv-d00011-J: Uses timestamp-based conflict resolution for approvals.
+    """
+    # Merge approvals by user (later approval wins)
+    local_approval_map = {a.user: a for a in local.approvals}
+    remote_approval_map = {a.user: a for a in remote.approvals}
+
+    all_users = set(local_approval_map.keys()) | set(remote_approval_map.keys())
+    merged_approvals = []
+
+    for user in all_users:
+        local_approval = local_approval_map.get(user)
+        remote_approval = remote_approval_map.get(user)
+
+        if local_approval and remote_approval:
+            # Take the later one (timestamp-based conflict resolution)
+            local_time = parse_iso_datetime(local_approval.at)
+            remote_time = parse_iso_datetime(remote_approval.at)
+            if remote_time >= local_time:
+                merged_approvals.append(remote_approval)
+            else:
+                merged_approvals.append(local_approval)
+        elif local_approval:
+            merged_approvals.append(local_approval)
+        else:
+            merged_approvals.append(remote_approval)
+
+    # Create merged request
+    merged = StatusRequest(
+        requestId=local.requestId,
+        reqId=local.reqId,
+        type=local.type,
+        fromStatus=local.fromStatus,
+        toStatus=local.toStatus,
+        requestedBy=local.requestedBy,
+        requestedAt=local.requestedAt,
+        justification=local.justification,
+        approvals=merged_approvals,
+        requiredApprovers=local.requiredApprovers,
+        state=local.state  # Will be recalculated
+    )
+
+    # Recalculate state based on merged approvals
+    merged._update_state()
+
+    return merged
+
+
+def merge_review_flags(local: ReviewFlag, remote: ReviewFlag) -> ReviewFlag:
+    """
+    Merge review flags from local and remote.
+
+    REQ-tv-d00011-G: Combines data from multiple user branches.
+    REQ-tv-d00011-J: Uses timestamp-based conflict resolution.
+
+    Strategy:
+    - If neither flagged, return unflagged
+    - If only one flagged, return that one
+    - If both flagged, take newer flag but merge scopes
+
+    Args:
+        local: Local review flag
+        remote: Remote review flag
+
+    Returns:
+        Merged ReviewFlag
+    """
+    # Neither flagged
+    if not local.flaggedForReview and not remote.flaggedForReview:
+        return ReviewFlag.cleared()
+
+    # Only one flagged
+    if not local.flaggedForReview:
+        return remote
+    if not remote.flaggedForReview:
+        return local
+
+    # Both flagged - take newer but merge scopes
+    local_time = parse_iso_datetime(local.flaggedAt)
+    remote_time = parse_iso_datetime(remote.flaggedAt)
+
+    # Merge scopes (unique values)
+    merged_scope = list(set(local.scope) | set(remote.scope))
+
+    if remote_time >= local_time:
+        # Remote is newer
+        return ReviewFlag(
+            flaggedForReview=True,
+            flaggedBy=remote.flaggedBy,
+            flaggedAt=remote.flaggedAt,
+            reason=remote.reason,
+            scope=merged_scope
+        )
+    else:
+        # Local is newer
+        return ReviewFlag(
+            flaggedForReview=True,
+            flaggedBy=local.flaggedBy,
+            flaggedAt=local.flaggedAt,
+            reason=local.reason,
+            scope=merged_scope
+        )
+
+
+# =============================================================================
+# Archive Operations
+# REQ-d00097: Review Package Archival
+# =============================================================================
+
+def archive_package(
+    repo_root: Path,
+    package_id: str,
+    reason: str,
+    user: str
+) -> bool:
+    """
+    Archive a package by moving it to the archive directory.
+
+    REQ-d00097-D: Archive SHALL be triggered by resolution, deletion, or manual action.
+    REQ-d00097-E: Deleting a package SHALL move it to archive rather than destroying.
+    REQ-d00097-C: Archive metadata SHALL be added to package.json.
+
+    Args:
+        repo_root: Repository root path
+        package_id: Package UUID
+        reason: Archive reason - one of "resolved", "deleted", "manual"
+        user: Username who triggered the archive
+
+    Returns:
+        True if archived successfully, False if package not found or already archived
+
+    Raises:
+        ValueError: If reason is not valid
+    """
+    from .models import (
+        ARCHIVE_REASON_RESOLVED,
+        ARCHIVE_REASON_DELETED,
+        ARCHIVE_REASON_MANUAL,
+    )
+
+    valid_reasons = {ARCHIVE_REASON_RESOLVED, ARCHIVE_REASON_DELETED, ARCHIVE_REASON_MANUAL}
+    if reason not in valid_reasons:
+        raise ValueError(f"Invalid archive reason: {reason}. Must be one of: {valid_reasons}")
+
+    # Load packages and find the one to archive
+    packages_file = load_packages(repo_root)
+    package = None
+    package_index = None
+
+    for i, p in enumerate(packages_file.packages):
+        if p.packageId == package_id:
+            package = p
+            package_index = i
+            break
+
+    if package is None:
+        return False
+
+    # Archive the package using its archive() method
+    package.archive(user, reason)
+
+    # Create archive directory structure
+    archive_pkg_dir = get_archived_package_dir(repo_root, package_id)
+    archive_pkg_dir.mkdir(parents=True, exist_ok=True)
+
+    # Save archived package metadata
+    archive_metadata_path = get_archived_package_metadata_path(repo_root, package_id)
+    atomic_write_json(archive_metadata_path, package.to_dict())
+
+    # Copy thread files to archive (v1 format - from .reviews/reqs/{req-id}/)
+    for req_id in package.reqIds:
+        source_threads_path = get_threads_path(repo_root, req_id)
+        if source_threads_path.exists():
+            dest_threads_path = get_archived_package_threads_path(repo_root, package_id, req_id)
+            dest_threads_path.parent.mkdir(parents=True, exist_ok=True)
+            # Copy the data
+            threads_data = read_json(source_threads_path)
+            atomic_write_json(dest_threads_path, threads_data)
+
+    # Remove package from active packages
+    del packages_file.packages[package_index]
+    save_packages(repo_root, packages_file)
+
+    return True
+
+
+def list_archived_packages(repo_root: Path) -> List[ReviewPackage]:
+    """
+    List all archived packages.
+
+    REQ-d00097: Provides read access to archived packages for the archive viewer.
+
+    Args:
+        repo_root: Repository root path
+
+    Returns:
+        List of archived ReviewPackage instances
+    """
+    archive_root = get_archive_dir(repo_root)
+    if not archive_root.exists():
+        return []
+
+    packages = []
+    for pkg_dir in archive_root.iterdir():
+        if pkg_dir.is_dir():
+            metadata_path = pkg_dir / 'package.json'
+            if metadata_path.exists():
+                try:
+                    data = read_json(metadata_path)
+                    package = ReviewPackage.from_dict(data)
+                    packages.append(package)
+                except (json.JSONDecodeError, KeyError):
+                    # Skip invalid package files
+                    continue
+
+    # Sort by archive date (most recent first)
+    packages.sort(
+        key=lambda p: p.archivedAt or '',
+        reverse=True
+    )
+
+    return packages
+
+
+def get_archived_package(repo_root: Path, package_id: str) -> Optional[ReviewPackage]:
+    """
+    Get a specific archived package by ID.
+
+    REQ-d00097: Provides read access to archived package details.
+
+    Args:
+        repo_root: Repository root path
+        package_id: Package UUID
+
+    Returns:
+        ReviewPackage if found, None otherwise
+    """
+    metadata_path = get_archived_package_metadata_path(repo_root, package_id)
+    if not metadata_path.exists():
+        return None
+
+    try:
+        data = read_json(metadata_path)
+        return ReviewPackage.from_dict(data)
+    except (json.JSONDecodeError, KeyError):
+        return None
+
+
+def load_archived_threads(
+    repo_root: Path,
+    package_id: str,
+    req_id: str
+) -> Optional[ThreadsFile]:
+    """
+    Load threads for a requirement from an archived package.
+
+    REQ-d00097-F: Archived data SHALL be read-only.
+
+    Args:
+        repo_root: Repository root path
+        package_id: Archived package UUID
+        req_id: Requirement ID
+
+    Returns:
+        ThreadsFile if found, None otherwise
+    """
+    threads_path = get_archived_package_threads_path(repo_root, package_id, req_id)
+    if not threads_path.exists():
+        return None
+
+    try:
+        data = read_json(threads_path)
+        return ThreadsFile.from_dict(data)
+    except (json.JSONDecodeError, KeyError):
+        return None
+
+
+def check_auto_archive(repo_root: Path, package_id: str, user: str) -> bool:
+    """
+    Check if a package should be auto-archived (all threads resolved) and archive if so.
+
+    REQ-d00097-D: Resolving all threads in a package SHALL trigger auto-archive.
+
+    Args:
+        repo_root: Repository root path
+        package_id: Package UUID
+        user: Username who resolved the last thread
+
+    Returns:
+        True if package was auto-archived, False otherwise
+    """
+    from .models import ARCHIVE_REASON_RESOLVED
+
+    # Load packages and find the one to check
+    packages_file = load_packages(repo_root)
+    package = None
+
+    for p in packages_file.packages:
+        if p.packageId == package_id:
+            package = p
+            break
+
+    if package is None:
+        return False
+
+    # Don't auto-archive default package
+    if package.isDefault:
+        return False
+
+    # Check if all threads in all reqs are resolved
+    all_resolved = True
+    has_threads = False
+
+    for req_id in package.reqIds:
+        threads_file = load_threads(repo_root, req_id)
+        for thread in threads_file.threads:
+            # Only count threads belonging to this package (if packageId is set)
+            if thread.packageId is None or thread.packageId == package_id:
+                has_threads = True
+                if not thread.resolved:
+                    all_resolved = False
+                    break
+
+        if not all_resolved:
+            break
+
+    # Archive if all threads are resolved and there was at least one thread
+    if has_threads and all_resolved:
+        return archive_package(repo_root, package_id, ARCHIVE_REASON_RESOLVED, user)
+
+    return False