elspais 0.11.2__py3-none-any.whl → 0.43.5__py3-none-any.whl

elspais/trace_view/scanning.py

@@ -1,213 +0,0 @@
-"""
-elspais.trace_view.scanning - Implementation file scanning.
-
-Provides functions to scan implementation files for requirement references
-and associate them with requirements.
-"""
-
-import re
-from pathlib import Path
-from typing import Dict, List, Optional, Set
-
-from elspais.trace_view.models import TraceViewRequirement
-
-
-def scan_implementation_files(
-    requirements: Dict[str, TraceViewRequirement],
-    impl_dirs: List[Path],
-    repo_root: Path,
-    mode: str = "core",
-    sponsor: Optional[str] = None,
-    quiet: bool = False,
-) -> None:
-    """Scan implementation files for requirement references.
-
-    This function modifies the requirements dict in-place, adding
-    implementation file references to each requirement.
-
-    Args:
-        requirements: Dict mapping requirement ID to TraceViewRequirement
-        impl_dirs: List of directories to scan for implementations
-        repo_root: Repository root for calculating relative paths
-        mode: Scanning mode ('core', 'sponsor', 'combined')
-        sponsor: Sponsor name for sponsor mode
-        quiet: If True, suppress progress messages
-    """
-    # Pattern to match requirement references in code comments
-    # Matches: REQ-p00001, REQ-o00042, REQ-d00156, REQ-CAL-d00001
-    req_ref_pattern = re.compile(r"REQ-(?:([A-Z]+)-)?([pod]\d{5})")
-
-    total_files_scanned = 0
-    total_refs_found = 0
-
-    for impl_dir in impl_dirs:
-        if not impl_dir.exists():
-            if not quiet:
-                print(f"   Warning: Implementation directory not found: {impl_dir}")
-            continue
-
-        # Apply mode-based filtering
-        if _should_skip_directory(impl_dir, mode, sponsor):
-            continue
-
-        # Determine file patterns based on directory
-        if impl_dir.name == "database":
-            patterns = ["*.sql"]
-        elif impl_dir.name in ["diary_app", "portal_app"]:
-            patterns = ["**/*.dart"]
-        else:
-            # Default: scan common code file types
-            patterns = ["**/*.dart", "**/*.sql", "**/*.py", "**/*.js", "**/*.ts"]
-
-        for pattern in patterns:
-            for file_path in impl_dir.glob(pattern):
-                if file_path.is_file():
-                    # Skip files in sponsor directories if not in the right mode
-                    if _should_skip_file(file_path, mode, sponsor):
-                        continue
-
-                    total_files_scanned += 1
-                    refs = _scan_file_for_requirements(
-                        file_path, req_ref_pattern, requirements, repo_root
-                    )
-                    total_refs_found += len(refs)
-
-    if not quiet:
-        print(f"   Scanned {total_files_scanned} implementation files")
-        print(f"   Found {total_refs_found} requirement references")
-
-
-def _scan_file_for_requirements(
-    file_path: Path,
-    pattern: re.Pattern,
-    requirements: Dict[str, TraceViewRequirement],
-    repo_root: Path,
-) -> Set[str]:
-    """Scan a single implementation file for requirement references.
-
-    Args:
-        file_path: Path to the file to scan
-        pattern: Compiled regex pattern for matching REQ references
-        requirements: Dict mapping requirement ID to TraceViewRequirement
-        repo_root: Repository root for calculating relative paths
-
-    Returns:
-        Set of requirement IDs found in the file
-    """
-    try:
-        content = file_path.read_text(encoding="utf-8")
-    except (UnicodeDecodeError, PermissionError):
-        # Skip files that can't be read
-        return set()
-
-    # Find all requirement IDs referenced in this file with their line numbers
-    referenced_reqs: Set[str] = set()
-
-    # Calculate relative path - handle external repos gracefully
-    try:
-        rel_path = file_path.relative_to(repo_root)
-    except ValueError:
-        # File is in external repo (not under repo_root)
-        try:
-            # Find the repo root of the external file (look for .git)
-            external_root = file_path
-            while external_root.parent != external_root:
-                if (external_root / ".git").exists():
-                    break
-                external_root = external_root.parent
-
-            if (external_root / ".git").exists():
-                # Use repo name + relative path within that repo
-                rel_path = Path(external_root.name) / file_path.relative_to(external_root)
-            else:
-                # Fallback: use just the filename
-                rel_path = Path(file_path.name)
-        except Exception:
-            # Ultimate fallback
-            rel_path = Path(file_path.name)
-
-    for match in pattern.finditer(content):
-        sponsor_prefix = match.group(1)  # May be None for core requirements
-        req_id_core = match.group(2)  # The core part (e.g., 'd00027')
-
-        # Build full requirement ID (with sponsor prefix if present)
-        if sponsor_prefix:
-            req_id = f"{sponsor_prefix}-{req_id_core}"
-        else:
-            req_id = req_id_core
-
-        referenced_reqs.add(req_id)
-
-        # Calculate line number from match position
-        line_num = content[: match.start()].count("\n") + 1
-
-        # Add (file_path, line_number) tuple to requirement's implementation_files
-        if req_id in requirements:
-            impl_entry = (str(rel_path), line_num)
-            # Avoid duplicates (same file, same line)
-            if impl_entry not in requirements[req_id].implementation_files:
-                requirements[req_id].implementation_files.append(impl_entry)
-
-    return referenced_reqs
-
-
-def _should_skip_directory(dir_path: Path, mode: str, sponsor: Optional[str]) -> bool:
-    """Check if a directory should be skipped based on mode.
-
-    Args:
-        dir_path: Path to the directory
-        mode: Scanning mode ('core', 'sponsor', 'combined')
-        sponsor: Sponsor name for sponsor mode
-
-    Returns:
-        True if the directory should be skipped
-    """
-    try:
-        parts = dir_path.parts
-        if "sponsor" in parts:
-            sponsor_idx = parts.index("sponsor")
-            if sponsor_idx + 1 < len(parts):
-                dir_sponsor = parts[sponsor_idx + 1]
-
-                # In core mode, skip all sponsor directories
-                if mode == "core":
-                    return True
-
-                # In sponsor mode, skip sponsor directories that don't match our sponsor
-                if mode == "sponsor" and sponsor and dir_sponsor != sponsor:
-                    return True
-
-        return False
-    except (ValueError, IndexError):
-        return False
-
-
-def _should_skip_file(file_path: Path, mode: str, sponsor: Optional[str]) -> bool:
-    """Check if a file should be skipped based on mode.
-
-    Args:
-        file_path: Path to the file
-        mode: Scanning mode ('core', 'sponsor', 'combined')
-        sponsor: Sponsor name for sponsor mode
-
-    Returns:
-        True if the file should be skipped
-    """
-    try:
-        parts = file_path.parts
-        if "sponsor" in parts:
-            sponsor_idx = parts.index("sponsor")
-            if sponsor_idx + 1 < len(parts):
-                file_sponsor = parts[sponsor_idx + 1]
-
-                # In core mode, skip all sponsor files
-                if mode == "core":
-                    return True
-
-                # In sponsor mode, skip sponsor files that don't match our sponsor
-                if mode == "sponsor" and sponsor and file_sponsor != sponsor:
-                    return True
-
-        return False
-    except (ValueError, IndexError):
-        return False

elspais/trace_view/specs/README.md

@@ -1,84 +0,0 @@
-# trace_view Specifications
-
-This directory contains formal requirements for the trace_view HTML generator refactoring and collaborative review system.
-
-## Scope
-
-These specifications define the requirements for:
-1. Refactoring `trace_view/html/generator.py` from a 3,420-line monolithic class to a maintainable Jinja2-based template architecture
-2. Adding a collaborative requirement review system with threaded comments, status workflows, and multi-user git-based synchronization
-
-## ID Convention
-
-Requirements in this directory use a **local scope prefix** to distinguish them from main `spec/` requirements:
-
-- **Format**: `REQ-tv-{p|d|o}{number}[-{assertion}]`
-- **Prefix**: `tv-` (trace_view local scope)
-- **Types**:
-  - `p` = PRD (Product Requirements)
-  - `d` = Dev (Development Specifications)
-  - `o` = Ops (Operations Documentation)
-
-**Examples**:
-- `REQ-tv-p00001` - Product requirement for HTML generator
-- `REQ-tv-d00003-B` - Assertion B of dev spec for JS extraction
-
-## Specification Files
-
-### HTML Generator (tv-p00001)
-
-| File | Type | Description |
-| ---- | ---- | ----------- |
-| `tv-p00001-html-generator.md` | PRD | High-level HTML generation requirements |
-| `tv-d00001-template-architecture.md` | Dev | Jinja2 template architecture |
-| `tv-d00002-css-extraction.md` | Dev | CSS extraction and embedding |
-| `tv-d00003-js-extraction.md` | Dev | JavaScript extraction and embedding |
-| `tv-d00004-build-embedding.md` | Dev | Build-time asset embedding |
-| `tv-d00005-test-format.md` | Dev | Test output format for elspais |
-
-### Review System (tv-p00002)
-
-| File | Type | Description |
-| ---- | ---- | ----------- |
-| `tv-p00002-review-system.md` | PRD | Collaborative requirement review system |
-| `tv-d00010-review-data-models.md` | Dev | Thread, Comment, Position data models |
-| `tv-d00011-review-storage.md` | Dev | Atomic JSON CRUD operations |
-| `tv-d00012-position-resolution.md` | Dev | Position anchoring with drift handling |
-| `tv-d00013-git-branches.md` | Dev | reviews/{package}/{user} branch management |
-| `tv-d00014-review-api-server.md` | Dev | Flask API endpoints |
-| `tv-d00015-status-modifier.md` | Dev | REQ status changes in spec files |
-| `tv-d00016-js-integration.md` | Dev | JavaScript modules integration |
-
-## Traceability
-
-```
-REQ-tv-p00001 (PRD: HTML Generator)
-├── REQ-tv-d00001 (Template Architecture)
-├── REQ-tv-d00002 (CSS Extraction)
-├── REQ-tv-d00003 (JS Extraction)
-├── REQ-tv-d00004 (Build Embedding)
-└── REQ-tv-d00005 (Test Format)
-
-REQ-tv-p00002 (PRD: Review System)
-├── REQ-tv-d00010 (Data Models)
-├── REQ-tv-d00011 (Storage Operations)
-├── REQ-tv-d00012 (Position Resolution)
-├── REQ-tv-d00013 (Git Branches)
-├── REQ-tv-d00014 (API Server)
-├── REQ-tv-d00015 (Status Modifier)
-└── REQ-tv-d00016 (JS Integration)
-```
-
-## Standard Compliance
-
-All specifications follow the `spec/requirements-spec.md` standard:
-
-- Normative content uses **SHALL** language
-- Assertions are labeled A-Z
-- Each requirement has a content hash footer
-- Rationale sections are non-normative
-
-## Related Documents
-
-- `/home/metagamer/.claude/plans/polymorphic-toasting-tiger.md` - Implementation plan
-- `spec/requirements-spec.md` - Requirements specification standard

elspais/trace_view/specs/tv-d00001-template-architecture.md

@@ -1,36 +0,0 @@
-# REQ-tv-d00001: Jinja2 Template Architecture
-
-**Level**: Dev | **Status**: Draft | **Implements**: REQ-tv-p00001
-
-## Assertions
-
-A. The HTMLGenerator class SHALL use a Jinja2 Environment for template rendering.
-
-B. Templates SHALL be loaded from a `templates/` subdirectory relative to the `html/` module.
-
-C. The template loader SHALL use FileSystemLoader with the templates directory path.
-
-D. The generator SHALL pass a context dictionary to template rendering containing: requirements data, coverage data, and configuration flags.
-
-E. The base template SHALL define the complete HTML document structure including DOCTYPE, html, head, and body elements.
-
-F. Template rendering SHALL support the `embed_content` flag to control data embedding mode.
-
-G. Template rendering SHALL support the `edit_mode` flag to control edit UI visibility.
-
-H. The generator class SHALL expose a `generate()` method with the same signature as the current implementation: `generate(embed_content: bool = False, edit_mode: bool = False) -> str`.
-
-I. Template errors SHALL be reported with meaningful error messages including template name and line number.
-
-## Rationale
-
-Jinja2 is the industry-standard Python templating engine, used by Flask, Ansible, and many other projects. It provides:
-- Clear separation of logic and presentation
-- Template inheritance and includes for code reuse
-- Excellent IDE support (syntax highlighting, autocomplete)
-- Compiled templates for performance
-- Well-documented and actively maintained
-
-The FileSystemLoader approach allows templates to be edited as standalone files with proper syntax highlighting, while the `generate()` method signature ensures backward compatibility.
-
-*End* *Jinja2 Template Architecture* | **Hash**: 0141b0f8

elspais/trace_view/specs/tv-d00002-css-extraction.md

@@ -1,37 +0,0 @@
-# REQ-tv-d00002: CSS Extraction
-
-**Level**: Dev | **Status**: Draft | **Implements**: REQ-tv-p00001
-
-## Assertions
-
-A. All CSS rules SHALL be extracted from Python string literals to a standalone `styles.css` file located at `templates/partials/styles.css`.
-
-B. The CSS file SHALL contain all styling currently generated by the following methods: `_generate_side_panel_css()`, `_generate_code_viewer_css()`, `_generate_legend_modal_css()`, and `_generate_file_picker_modal_css()`.
-
-C. The CSS file SHALL be a valid CSS document that can be parsed by standard CSS tools and linters.
-
-D. The CSS file SHALL be readable by IDEs with proper syntax highlighting and autocomplete support.
-
-E. CSS content SHALL be loaded from the file at template render time.
-
-F. The extracted CSS SHALL produce visually identical output to the current inline CSS generation.
-
-G. CSS selectors and rules SHALL NOT be duplicated between the extracted file and any remaining inline styles.
-
-H. The CSS file SHALL use consistent formatting: 4-space indentation, one property per line, and blank lines between rule blocks.
-
-## Rationale
-
-The current implementation embeds 629 lines of CSS across 4 Python methods as string literals. This approach:
-- Prevents IDE CSS support (linting, autoprefixer, minification)
-- Makes it difficult to detect duplicate selectors
-- Couples styling changes to Python code changes
-- Prevents use of CSS tooling
-
-Extracting CSS to a standalone file enables:
-- Proper IDE support for CSS editing
-- Use of CSS linters and formatters
-- Independent modification of styles
-- Easier review of styling changes
-
-*End* *CSS Extraction* | **Hash**: f31a509b

elspais/trace_view/specs/tv-d00003-js-extraction.md

@@ -1,43 +0,0 @@
-# REQ-tv-d00003: JavaScript Extraction
-
-**Level**: Dev | **Status**: Draft | **Implements**: REQ-tv-p00001
-
-## Assertions
-
-A. All JavaScript code SHALL be extracted from Python string literals to a standalone `scripts.js` file located at `templates/partials/scripts.js`.
-
-B. The JavaScript file SHALL contain all functionality currently generated by `_generate_side_panel_js()` and any other JavaScript-generating methods.
-
-C. The JavaScript file SHALL be a valid JavaScript document that can be parsed by standard JavaScript tools and linters.
-
-D. The JavaScript file SHALL be readable by IDEs with proper syntax highlighting, autocomplete, and error detection.
-
-E. JavaScript code SHALL be organized using a module pattern with a single namespace object (e.g., `TraceView`).
-
-F. The module pattern SHALL group related functions into logical sub-objects: `panel`, `codeViewer`, `editMode`, `state`.
-
-G. JavaScript content SHALL be loaded from the file at template render time.
-
-H. The extracted JavaScript SHALL produce functionally identical behavior to the current inline JavaScript generation.
-
-I. Global state variables (e.g., `reqCardStack`, `pendingMoves`) SHALL be encapsulated within the module namespace.
-
-J. Event handlers for dynamically created elements SHALL be bound using `addEventListener` rather than inline `onclick` attributes.
-
-K. The JavaScript file SHALL include JSDoc comments for all public functions.
-
-## Rationale
-
-The current implementation embeds 736 lines of JavaScript in `_generate_side_panel_js()` as a Python string literal containing 28 functions. This approach:
-- Prevents IDE JavaScript support (linting, type checking, error detection)
-- Makes debugging difficult (errors reference Python line numbers, not JS)
-- Couples behavior changes to Python code changes
-- Uses global variables without encapsulation
-
-The module pattern provides:
-- Clear namespace to avoid global pollution
-- Logical grouping of related functionality
-- Encapsulated state management
-- Better testability
-
-*End* *JavaScript Extraction* | **Hash**: 297cf4c0

elspais/trace_view/specs/tv-d00004-build-embedding.md

@@ -1,40 +0,0 @@
-# REQ-tv-d00004: Build-time Asset Embedding
-
-**Level**: Dev | **Status**: Draft | **Implements**: REQ-tv-p00001
-
-## Assertions
-
-A. The generator SHALL embed CSS content inline within `<style>` tags in the generated HTML.
-
-B. The generator SHALL embed JavaScript content inline within `<script>` tags in the generated HTML.
-
-C. Asset files SHALL be read from disk at template render time, not at module import time.
-
-D. The generator SHALL provide a helper method `_load_css()` that reads and returns the CSS file content.
-
-E. The generator SHALL provide a helper method `_load_js()` that reads and returns the JavaScript file content.
-
-F. File reading errors SHALL raise informative exceptions including the expected file path.
-
-G. The generated HTML document SHALL be completely self-contained with no external file dependencies (except for CDN libraries in embedded mode).
-
-H. The embedding approach SHALL support Jinja2 template variables within embedded CSS and JavaScript content for dynamic values such as `base_path` and `repo_root`.
-
-I. The generator SHALL cache file content during a single render operation to avoid redundant disk reads.
-
-J. The embedded content SHALL be properly escaped to prevent HTML injection from file content (e.g., `</script>` within JavaScript).
-
-## Rationale
-
-The goal is to develop with separate files for IDE support while producing a single self-contained HTML file for portability. This "develop separate, embed at build time" approach provides:
-- IDE support during development
-- Single-file distribution for end users
-- No web server required to view reports
-- Works offline after generation
-
-The caching and lazy loading approach ensures:
-- Files are read only when needed
-- Multiple templates can share the same CSS/JS without re-reading
-- Fresh content on each render (no stale module-level cache)
-
-*End* *Build-time Asset Embedding* | **Hash**: 177c0fd7

elspais/trace_view/specs/tv-d00005-test-format.md

@@ -1,78 +0,0 @@
-# REQ-tv-d00005: Elspais Test Output Format
-
-**Level**: Dev | **Status**: Draft | **Implements**: REQ-tv-p00001
-
-## Assertions
-
-A. Test runs SHALL produce a JSON output file at `tests/results/trace_results.json`.
-
-B. The JSON output SHALL conform to format version "1.0" as specified in this requirement.
-
-C. Each test result entry SHALL include: `requirement_id`, `assertion_id`, `full_id`, `test_name`, `test_file`, `test_line`, `status`, `duration_ms`, `error_message`, and `timestamp`.
-
-D. The `requirement_id` field SHALL contain the base requirement ID without assertion suffix (e.g., `REQ-tv-d00001`).
-
-E. The `assertion_id` field SHALL contain only the assertion letter (e.g., `A`) or null if the test covers the entire requirement.
-
-F. The `full_id` field SHALL contain the complete reference including assertion suffix if applicable (e.g., `REQ-tv-d00001-A`).
-
-G. The `status` field SHALL be one of: `passed`, `failed`, or `skipped`.
-
-H. The output SHALL include a `summary` object with: `total`, `passed`, `failed`, `skipped`, and `coverage_percentage` fields.
-
-I. Test functions SHALL include the requirement ID in their docstring for extraction by the reporter.
-
-J. A pytest plugin SHALL be implemented in `conftest.py` to generate the output automatically.
-
-K. The reporter SHALL extract requirement IDs from test docstrings using the pattern `REQ-tv-[pdo]\d{5}(?:-[A-Z])?`.
-
-L. The output file SHALL be generated at the end of the pytest session via `pytest_sessionfinish` hook.
-
-M. The `generated_at` field SHALL contain an ISO 8601 formatted timestamp.
-
-## Rationale
-
-Elspais requires structured test results to incorporate into the traceability matrix. The JSON format enables:
-- Automated parsing and integration
-- Bidirectional traceability (requirements to tests, tests to requirements)
-- Coverage reporting at the assertion level
-- Historical tracking of test results
-
-The pytest plugin approach ensures:
-- Automatic generation without manual steps
-- Consistent format across all test runs
-- Integration with existing pytest workflows
-- No changes required to test execution commands
-
-## Format Example
-
-```json
-{
-  "format_version": "1.0",
-  "generated_at": "2026-01-03T12:34:56Z",
-  "test_run_id": "abc123",
-  "results": [
-    {
-      "requirement_id": "REQ-tv-d00001",
-      "assertion_id": "A",
-      "full_id": "REQ-tv-d00001-A",
-      "test_name": "test_jinja2_environment_used",
-      "test_file": "test_template_architecture.py",
-      "test_line": 15,
-      "status": "passed",
-      "duration_ms": 12,
-      "error_message": null,
-      "timestamp": "2026-01-03T12:34:56.123Z"
-    }
-  ],
-  "summary": {
-    "total": 26,
-    "passed": 24,
-    "failed": 2,
-    "skipped": 0,
-    "coverage_percentage": 92.3
-  }
-}
-```
-
-*End* *Elspais Test Output Format* | **Hash**: 5219f9e0

elspais/trace_view/specs/tv-d00010-review-data-models.md

@@ -1,33 +0,0 @@
-# REQ-tv-d00010: Review Data Models
-
-**Level**: Dev | **Status**: Draft | **Implements**: REQ-tv-p00002
-
-## Assertions
-
-A. CommentPosition, Comment, Thread, ReviewFlag, StatusRequest, Approval, ReviewSession, ReviewConfig, and ReviewPackage SHALL be implemented as dataclasses.
-
-B. PositionType, RequestState, and ApprovalDecision SHALL be implemented as string enums for JSON compatibility.
-
-C. Each dataclass SHALL implement a `to_dict()` method returning a JSON-serializable dictionary.
-
-D. Each dataclass SHALL implement a `from_dict(data)` class method for deserialization from dictionaries.
-
-E. Each dataclass SHALL implement a `validate()` method returning a tuple of `(is_valid: bool, errors: List[str])`.
-
-F. Thread, Comment, StatusRequest, and ReviewPackage SHALL implement factory methods (`create()`) that auto-generate IDs and timestamps.
-
-G. ThreadsFile, StatusFile, and PackagesFile container classes SHALL manage file-level JSON structure with version tracking.
-
-H. CommentPosition SHALL support four anchor types: LINE (specific line), BLOCK (line range), WORD (keyword occurrence), and GENERAL (whole requirement).
-
-I. StatusRequest SHALL automatically calculate its state based on approval votes and configured approval rules.
-
-J. All dataclasses SHALL use UTC timestamps in ISO 8601 format.
-
-## Rationale
-
-Dataclasses provide immutable-by-default data structures with auto-generated `__init__`, `__repr__`, and comparison methods. The `to_dict`/`from_dict` pattern enables clean JSON serialization without requiring JSON encoder customization. The `validate()` method enables explicit validation at boundaries rather than relying on exceptions during construction.
-
-The factory methods hide ID generation and timestamp creation from callers, ensuring consistent data creation patterns across the codebase.
-
-*End* *Review Data Models* | **Hash**: 00000000

elspais/trace_view/specs/tv-d00011-review-storage.md

@@ -1,33 +0,0 @@
-# REQ-tv-d00011: Review Storage Operations
-
-**Level**: Dev | **Status**: Draft | **Implements**: REQ-tv-p00002
-
-## Assertions
-
-A. All JSON file writes SHALL use atomic write operations via temporary file creation followed by rename.
-
-B. Thread storage operations SHALL support: `load_threads()`, `save_threads()`, `add_thread()`, `add_comment_to_thread()`, `resolve_thread()`, and `unresolve_thread()`.
-
-C. Status request storage operations SHALL support: `load_status_requests()`, `save_status_requests()`, `create_status_request()`, `add_approval()`, and `mark_request_applied()`.
-
-D. Review flag storage operations SHALL support: `load_review_flag()` and `save_review_flag()`.
-
-E. Package storage operations SHALL support: `load_packages()`, `save_packages()`, `create_package()`, `update_package()`, `delete_package()`, `add_req_to_package()`, and `remove_req_from_package()`.
-
-F. Config storage operations SHALL support: `load_config()` and `save_config()` for system-wide settings.
-
-G. Merge operations SHALL support: `merge_threads()`, `merge_status_files()`, and `merge_review_flags()` for combining data from multiple user branches.
-
-H. Storage paths SHALL follow the convention: `.reviews/reqs/{normalized-req-id}/threads.json`, `.reviews/reqs/{normalized-req-id}/status.json`, `.reviews/packages.json`, and `.reviews/config.json`.
-
-I. Requirement IDs in paths SHALL be normalized by replacing colons and slashes with underscores.
-
-J. The merge strategy SHALL deduplicate by ID (threadId, requestId) and use timestamp-based conflict resolution for divergent edits.
-
-## Rationale
-
-Atomic writes via temp+rename prevent data corruption from interrupted writes or concurrent access. The normalized path convention ensures filesystem compatibility across operating systems while maintaining readable directory structures.
-
-The merge operations enable the multi-user review workflow where each user works on their own branch and merges are performed when viewing consolidated package data.
-
-*End* *Review Storage Operations* | **Hash**: 00000000

elspais/trace_view/specs/tv-d00012-position-resolution.md

@@ -1,33 +0,0 @@
-# REQ-tv-d00012: Position Resolution
-
-**Level**: Dev | **Status**: Draft | **Implements**: REQ-tv-p00002
-
-## Assertions
-
-A. The position resolution system SHALL resolve CommentPosition anchors to current document coordinates.
-
-B. ResolvedPosition SHALL indicate confidence level: EXACT (hash matches), APPROXIMATE (fallback matched), or UNANCHORED (no match found).
-
-C. When the document hash matches the position's `hashWhenCreated`, the position SHALL resolve with EXACT confidence using stored coordinates.
-
-D. When the document hash differs, the system SHALL attempt fallback resolution using the `fallbackContext` field.
-
-E. For LINE positions, fallback resolution SHALL search for the context string and return the matching line number.
-
-F. For BLOCK positions, fallback resolution SHALL search for the context and expand to include the original block size.
-
-G. For WORD positions, fallback resolution SHALL search for the keyword and return the Nth occurrence based on `keywordOccurrence`.
-
-H. GENERAL positions SHALL always resolve with EXACT confidence since they apply to the entire requirement.
-
-I. ResolvedPosition SHALL include a `resolutionPath` field describing which fallback strategy was used.
-
-J. When no fallback succeeds, the position SHALL resolve as UNANCHORED with the original position preserved for manual re-anchoring.
-
-## Rationale
-
-Position resolution enables comments to "survive" requirement edits. When a requirement is modified, its content hash changes, invalidating stored positions. The fallback strategies attempt to find where the commented content moved to, maintaining the spatial relationship between comments and content.
-
-The confidence levels allow the UI to display visual indicators (e.g., yellow warning for approximate, red for unanchored) so users know when manual review may be needed.
-
-*End* *Position Resolution* | **Hash**: 00000000

elspais/trace_view/specs/tv-d00013-git-branches.md

@@ -1,31 +0,0 @@
-# REQ-tv-d00013: Git Branch Management
-
-**Level**: Dev | **Status**: Draft | **Implements**: REQ-tv-p00002
-
-## Assertions
-
-A. Review branches SHALL follow the naming convention `reviews/{package_id}/{username}`.
-
-B. `get_review_branch_name(package_id, user)` SHALL return the formatted branch name.
-
-C. `parse_review_branch_name(branch_name)` SHALL extract and return a tuple of `(package_id, username)` from a valid branch name.
-
-D. `is_review_branch(branch_name)` SHALL return True only for branches matching the `reviews/{package}/{user}` pattern.
-
-E. `list_package_branches(repo_root, package_id)` SHALL return all branch names for a given package across all users.
-
-F. `get_current_package_context(repo_root)` SHALL return `(package_id, username)` when on a review branch, or `(None, None)` otherwise.
-
-G. `commit_and_push_reviews(repo_root, message)` SHALL commit all changes in `.reviews/` and push to the remote tracking branch.
-
-H. Branch operations SHALL detect and report conflicts without causing data loss.
-
-I. `fetch_package_branches(repo_root, package_id)` SHALL fetch all remote branches for a package to enable merge operations.
-
-## Rationale
-
-The branch-per-user-per-package model enables isolated work with eventual consistency. Each reviewer can work offline on their own branch, and data is consolidated when viewing the package by merging from all contributor branches.
-
-The naming convention makes it easy to discover all contributors to a package review and to filter branches by package.
-
-*End* *Git Branch Management* | **Hash**: 00000000