elspais 0.9.1__tar.gz → 0.9.3__tar.gz

{elspais-0.9.1 → elspais-0.9.3}/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-01-05
+
+### Added
+- Git-based change detection with new `changed` command
+  - `elspais changed`: Show uncommitted changes to spec files
+  - `elspais changed --json`: JSON output for programmatic use
+  - `elspais changed --all`: Include all changed files, not just spec/
+  - `elspais changed --base-branch`: Compare vs different branch
+- New `src/elspais/core/git.py` module with functions:
+  - `get_git_changes()`: Main entry point for git change detection
+  - `get_modified_files()`: Detect modified/untracked files via git status
+  - `get_changed_vs_branch()`: Files changed vs main/master branch
+  - `detect_moved_requirements()`: Detect requirements moved between files
+- 23 new tests for git functionality
+
+## [0.9.2] - 2026-01-05
+
+### Added
+- `id.duplicate` rule documentation in `docs/rules.md`
+- Dynamic version detection using `importlib.metadata`
+
+### Changed
+- Enhanced ParseResult API documentation in CLAUDE.md to explain warning handling
+- Updated CLAUDE.md with git.py module description
+
 ## [0.9.1] - 2026-01-03
 
 ### Changed

{elspais-0.9.1 → elspais-0.9.3}/PKG-INFO

@@ -1,15 +1,14 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: elspais
-Version: 0.9.1
+Version: 0.9.3
 Summary: Requirements validation and traceability tools - L-Space connects all libraries
-Home-page: https://github.com/anspar/elspais
-Author: Anspar
-Author-email: dev@anspar.io
-License: MIT
+Project-URL: Homepage, https://github.com/anspar/elspais
 Project-URL: Documentation, https://github.com/anspar/elspais#readme
 Project-URL: Repository, https://github.com/anspar/elspais
 Project-URL: Issues, https://github.com/anspar/elspais/issues
 Project-URL: Changelog, https://github.com/anspar/elspais/blob/main/CHANGELOG.md
+Author-email: Anspar <dev@anspar.io>
+License-File: LICENSE
 Keywords: documentation,requirements,specifications,traceability,validation
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
@@ -57,18 +56,50 @@ Description-Content-Type: text/markdown
 
 ## Installation
 
+### For End Users
+
 ```bash
+# Standard installation
 pip install elspais
+
+# Recommended for CLI tools: Isolated installation
+pipx install elspais
 ```
 
-Or install from source:
+### For Development
 
 ```bash
 git clone https://github.com/anspar/elspais.git
 cd elspais
-pip install -e .
+pip install -e ".[dev]"
+```
+
+### For Docker and CI/CD
+
+For faster installation in containerized environments, consider [uv](https://github.com/astral-sh/uv):
+
+```dockerfile
+# Example Dockerfile
+FROM python:3.11-slim
+
+# Copy uv binary
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Install elspais (10-100x faster than pip)
+RUN uv pip install --system --no-cache elspais==0.9.1
 ```
 
+```yaml
+# Example GitHub Actions
+- name: Install uv
+  uses: astral-sh/setup-uv@v2
+
+- name: Install elspais
+  run: uv pip install --system elspais==0.9.1
+```
+
+**Note:** For regulated/medical software projects, always pin the exact version for reproducibility.
+
 ## Quick Start
 
 ### Initialize a Repository
@@ -185,22 +216,28 @@ See [docs/configuration.md](docs/configuration.md) for full reference.
 elspais expects requirements in Markdown format:
 
 ```markdown
-### REQ-d00001: Requirement Title
+# REQ-d00001: Requirement Title
 
-**Level**: Dev | **Implements**: p00001 | **Status**: Active
+**Level**: Dev | **Status**: Active | **Implements**: REQ-p00001
 
-The system SHALL provide user authentication.
+## Assertions
 
-**Rationale**: Security requires identity verification.
+A. The system SHALL provide user authentication via email/password.
+B. Sessions SHALL expire after 30 minutes of inactivity.
 
-**Acceptance Criteria**:
-- Users can log in with email/password
-- Session expires after 30 minutes of inactivity
+## Rationale
+
+Security requires identity verification.
 
 *End* *Requirement Title* | **Hash**: a1b2c3d4
 ---
 ```
 
+Key format elements:
+- **Assertions section**: Labeled A-Z, each using SHALL for normative statements
+- **One-way traceability**: Children reference parents via `Implements:`
+- **Hash footer**: SHA-256 hash for change detection
+
 ## ID Pattern Examples
 
 elspais supports multiple ID formats:

{elspais-0.9.1 → elspais-0.9.3}/README.md

@@ -18,18 +18,50 @@
 
 ## Installation
 
+### For End Users
+
 ```bash
+# Standard installation
 pip install elspais
+
+# Recommended for CLI tools: Isolated installation
+pipx install elspais
 ```
 
-Or install from source:
+### For Development
 
 ```bash
 git clone https://github.com/anspar/elspais.git
 cd elspais
-pip install -e .
+pip install -e ".[dev]"
+```
+
+### For Docker and CI/CD
+
+For faster installation in containerized environments, consider [uv](https://github.com/astral-sh/uv):
+
+```dockerfile
+# Example Dockerfile
+FROM python:3.11-slim
+
+# Copy uv binary
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Install elspais (10-100x faster than pip)
+RUN uv pip install --system --no-cache elspais==0.9.1
 ```
 
+```yaml
+# Example GitHub Actions
+- name: Install uv
+  uses: astral-sh/setup-uv@v2
+
+- name: Install elspais
+  run: uv pip install --system elspais==0.9.1
+```
+
+**Note:** For regulated/medical software projects, always pin the exact version for reproducibility.
+
 ## Quick Start
 
 ### Initialize a Repository
@@ -146,22 +178,28 @@ See [docs/configuration.md](docs/configuration.md) for full reference.
 elspais expects requirements in Markdown format:
 
 ```markdown
-### REQ-d00001: Requirement Title
+# REQ-d00001: Requirement Title
 
-**Level**: Dev | **Implements**: p00001 | **Status**: Active
+**Level**: Dev | **Status**: Active | **Implements**: REQ-p00001
 
-The system SHALL provide user authentication.
+## Assertions
 
-**Rationale**: Security requires identity verification.
+A. The system SHALL provide user authentication via email/password.
+B. Sessions SHALL expire after 30 minutes of inactivity.
 
-**Acceptance Criteria**:
-- Users can log in with email/password
-- Session expires after 30 minutes of inactivity
+## Rationale
+
+Security requires identity verification.
 
 *End* *Requirement Title* | **Hash**: a1b2c3d4
 ---
 ```
 
+Key format elements:
+- **Assertions section**: Labeled A-Z, each using SHALL for normative statements
+- **One-way traceability**: Children reference parents via `Implements:`
+- **Hash footer**: SHA-256 hash for change detection
+
 ## ID Pattern Examples
 
 elspais supports multiple ID formats:

elspais-0.9.3/docs/roadmap/llm-reformatting-integration.md

@@ -0,0 +1,113 @@
+# LLM-Assisted Reformatting Integration
+
+**Parent**: [requirements-format-enhancements.md](./requirements-format-enhancements.md)
+**Date**: 2026-01-04
+**Ticket**: CUR-514
+
+---
+
+## Decision
+
+Integrate reformatting capability into elspais with custom handler fallback.
+
+## Problem
+
+The `reformat_reqs` tool currently requires Claude Code. Users may want to use different LLMs or traditional scripts.
+
+---
+
+## Solution Architecture
+
+```
+elspais reformat REQ-p00043
+         │
+         ├── Claude Code available? → Use built-in Claude integration
+         │
+         └── Not available? → Check for custom handler
+                    │
+                    ├── Handler configured? → Load and execute
+                    │
+                    └── Not configured? → Emit helpful error with options
+```
+
+---
+
+## Configuration
+
+```toml
+# .elspais.toml
+[reformat]
+# Default: use Claude Code if available
+# Custom: provide path to Python module with handler function
+handler = "tools/custom_reformatter.py:reformat_requirement"
+```
+
+---
+
+## Custom Handler Interface
+
+```python
+# tools/custom_reformatter.py
+def reformat_requirement(
+    req_id: str,
+    title: str,
+    body: str,
+    rationale: str | None
+) -> dict:
+    """
+    Transform requirement content to assertion-based format.
+
+    Args:
+        req_id: Requirement ID (e.g., "REQ-p00043")
+        title: Requirement title
+        body: Current requirement body text
+        rationale: Existing rationale if present
+
+    Returns:
+        {
+            "rationale": str,  # New or refined rationale
+            "assertions": list[str]  # List of assertion statements
+        }
+    """
+    # Implementation using any method:
+    # - Different LLM API (OpenAI, local model, etc.)
+    # - Rule-based transformation
+    # - Template-based approach
+    pass
+```
+
+---
+
+## Error Message When No Handler
+
+```
+Error: Claude Code not configured and no custom handler specified.
+
+To use LLM-assisted reformatting, either:
+1. Configure Claude Code (see: https://claude.ai/code)
+2. Provide a custom handler in .elspais.toml:
+
+   [reformat]
+   handler = "path/to/handler.py:function_name"
+
+   The handler function should accept (req_id, title, body, rationale)
+   and return {"rationale": str, "assertions": list[str]}
+
+   See: docs/elspais-custom-handlers.md for examples.
+```
+
+---
+
+## Implementation Phase
+
+**Phase 4** (8-16 hours):
+
+1. Integrate reformat_reqs functionality into elspais
+2. Add custom handler fallback mechanism
+3. Implement helpful error messages
+4. Document custom handler interface
+
+**Deliverables**:
+- `elspais reformat` command
+- Custom handler documentation
+- Example handlers (OpenAI, rule-based)

elspais-0.9.3/docs/roadmap/new-format.md

@@ -0,0 +1,193 @@
+# ADR-010: Requirements Format Enhancements
+
+**Date**: 2026-01-04
+**Deciders**: Development Team
+**Compliance**: FDA 21 CFR Part 11, Requirement Traceability
+
+## Status
+
+Accepted
+
+---
+
+## Context
+
+The current assertion-based requirements format provides strong foundations:
+- Clear separation between normative (Assertions) and informative (Rationale) content
+- Labeled assertions (A, B, C...) enable precise traceability
+- SHALL-based prescriptive language enforces testability
+- Hash-based change detection provides tamper-evidence
+- Three-tier hierarchy: PRD → OPS → DEV with `Implements:` references
+
+However, gaps exist:
+- **Cross-Cutting Concerns**: Security, compliance, multi-sponsor requirements scattered across files with no matrix view to see how functions span components
+- **Verification Tracking**: No explicit field indicating how a requirement is validated; mix of testable requirements and declared axioms without distinction
+
+Industry standards (IEEE 29148, EARS, INCOSE, Planguage, IEC 62304) were evaluated for potential enhancements.
+
+---
+
+## Decision
+
+### 1. Add Type Field
+
+Categorize requirements as artifacts (things) or functions (capabilities) to enable matrix views.
+
+**Four Semantic Categories** (2 current, 2 reserved):
+
+| Category | Status | Description | Allowed Synonyms |
+|----------|--------|-------------|------------------|
+| **Artifact** | Current | Instantiated, concrete things | `system`, `component`, `application`, `module`, `service` |
+| **Function** | Current | Capabilities, characteristics | `feature`, `characteristic`, `capability`, `restriction`, `standard`, `regulation` |
+| **Interface** | Reserved | Abstract definitions, not instantiated | TBD |
+| **Constraint** | Reserved | Parameters separated from process | TBD |
+
+**Matrix View Enabled**:
+- Rows: Artifact-type requirements (system, component, ...)
+- Columns: Function-type requirements (feature, regulation, ...)
+- Cells: Child requirements that implement both an artifact AND a function
+
+### 2. Add Validation Field (Optional)
+
+Distinguish between testable requirements and declared axioms.
+
+| Canonical | Synonyms | Status | Description |
+|-----------|----------|--------|-------------|
+| `test` | `tested`, `testing` | Current | Verified through automated or manual testing |
+| `inspect` | `inspected`, `inspection` | Current | Verified through document/code review |
+| `analysis` | - | Reserved | Verified through static analysis, modeling |
+| `demonstration` | - | Reserved | Verified through proof-of-concept |
+
+**Default**: If validation is omitted, defaults to `test`. Most requirements are testable.
+
+### 3. Updated Header Format
+
+**Current Format**:
+```markdown
+# REQ-p00043: Clinical Diary Mobile Application
+
+**Level**: PRD | **Status**: Draft | **Implements**: p00044
+```
+
+**New Format**:
+```markdown
+# REQ-p00043: Clinical Diary Mobile Application
+**PRD** component - Draft
+**Implements**: p00044
+## end Clinical Diary Mobile Application
+```
+
+**Format Specification**:
+- Line 1: `# REQ-{id}: {title}`
+- Line 2: `**{LEVEL}** {type} [({validation})] - {status}`
+  - `{validation}` is optional; defaults to `test` if omitted
+  - Use `(inspect)` for declarations/definitions verified by review
+- Line 3: `**Implements**: {parent_ids}` (only if has parents)
+- End: `## end {title}`
+
+### 4. Bidirectional Traceability via Tooling
+
+Two-way links in files are error-prone and create maintenance burden. Software can derive bidirectional views from one-way data.
+
+- Files maintain one-way `Implements:` references (current approach)
+- elspais generates reverse lookup tables at runtime
+- Traceability views show both directions without file redundancy
+
+### 5. Rejected Enhancements
+
+| Enhancement | Decision | Rationale |
+|-------------|----------|-----------|
+| **Tags** | Omit | Type field handles cross-cutting via multi-parent Implements |
+| **Priority** | Omit | All spec'd requirements are necessary; no decision value |
+| **Risk** | Omit | Belongs in ADRs, applies to decisions not requirements |
+| **EARS syntax** | Omit | Limited value; natural writing produces these patterns |
+| **Planguage** | Omit | Verbosity harms readability |
+| **Owner field** | Omit | Tracked in tickets/project management |
+
+---
+
+## Consequences
+
+### Positive
+- Matrix views enable cross-cutting concern visualization
+- Validation field distinguishes testable from declared requirements
+- Compact header format improves readability
+- No file redundancy from bidirectional links
+- Synonym support allows natural writing while enabling tooling
+
+### Negative
+- Existing requirements need backfilling with Type and Validation
+- elspais tooling requires updates
+
+### Neutral
+- Reserved categories (Interface, Constraint) available for future needs
+- Risk assessment continues to belong in ADRs
+
+---
+
+## elspais Configuration
+
+```toml
+# .elspais.toml
+
+[metadata]
+enabled = true
+
+[metadata.type]
+required = true
+categories = ["artifact", "function", "interface", "constraint"]
+artifact_synonyms = ["system", "component", "application", "module", "service"]
+function_synonyms = ["feature", "characteristic", "capability", "restriction", "standard", "regulation"]
+reserved_categories = ["interface", "constraint"]
+
+[metadata.validation]
+required = false
+methods = ["test", "inspect", "analyze", "demonstrate"]
+default = "test"
+test_synonyms = ["test", "tested", "testing"]
+inspect_synonyms = ["inspect", "inspected", "inspection"]
+reserved_methods = ["analysis", "demonstration"]
+```
+
+---
+
+## Matrix View Generation
+
+**Command**:
+```bash
+elspais matrix --format html > reports/requirement-matrix.html
+elspais matrix --format csv > reports/requirement-matrix.csv
+```
+
+**Generated Matrix**:
+
+| Artifact ↓ / Function → | Encryption | Audit Trail | Multi-Sponsor | Offline Sync |
+|-------------------------|------------|-------------|---------------|--------------|
+| **Diary App (p00043)** | p01070 | p01071 | p00008 | p00006 |
+| **Web App (p01042)** | p01072 | p01073 | p00008 | - |
+| **Portal (p00045)** | p01074 | p01075 | p00009 | - |
+| **Database (p00046)** | p01076 | p00004 | p00003 | - |
+
+---
+
+## Related Documents
+
+- [PlantUML Diagram Support](../research/plantuml-diagram-support.md)
+- [LLM Reformatting Integration](../research/llm-reformatting-integration.md)
+- [Implementation Roadmap](https://github.com/elspais/docs/roadmap/requirements-format-enhancements.md)
+
+---
+
+## References
+
+### Industry Standards
+- [IEEE SA - ISO/IEC/IEEE 29148-2018](https://standards.ieee.org/standard/29148-2018.html)
+- [INCOSE Guide to Writing Requirements](https://www.incose.org/docs/default-source/working-groups/requirements-wg/rwg_products/incose_rwg_gtwr_summary_sheet_2022.pdf)
+
+### Diagram Tools
+- [PlantUML](https://plantuml.com/)
+- [C4 Model with PlantUML](https://c4model.com/)
+
+### Risk Management (for ADR context)
+- [ISO 14971 - Medical Device Risk Management](https://www.iso.org/standard/72704.html)
+- [FMEA Handbook](https://www.aiag.org/quality/automotive-core-tools/fmea)

elspais-0.9.3/docs/roadmap/plantuml-diagram-support.md

@@ -0,0 +1,90 @@
+# PlantUML Diagram Support
+
+**Parent**: [requirements-format-enhancements.md](./requirements-format-enhancements.md)
+**Date**: 2026-01-04
+**Ticket**: CUR-514
+
+---
+
+## Decision
+
+Implement PlantUML generation and potentially parsing.
+
+## Rationale
+
+- **Text-based**: version-controllable, diff-friendly
+- **Widely supported**: renders in GitHub, IDEs, CI/CD
+- **Linkable**: can annotate with requirement references
+- **Infrastructure integration**: can map to/from Terraform IaC files
+
+---
+
+## Use Cases
+
+1. **Generate from requirements**: `elspais diagram --format plantuml`
+2. **Parse diagrams**: Extract requirement references from annotated diagrams
+3. **Cross-reference**: Link diagrams to requirements, operations manuals
+
+---
+
+## Example Output
+
+```plantuml
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
+
+title Clinical Diary Platform - Requirement Hierarchy
+
+package "Platform (REQ-p00044)" {
+  [Diary App\nREQ-p00043] as diary
+  [Web App\nREQ-p01042] as web
+  [Portal\nREQ-p00045] as portal
+  [Database\nREQ-p00046] as db
+}
+
+package "Cross-Cutting Functions" {
+  [Encryption\nREQ-p01009] as encrypt
+  [Audit Trail\nREQ-p00004] as audit
+}
+
+diary --> encrypt : implements
+web --> encrypt : implements
+portal --> audit : implements
+db --> audit : implements
+@enduml
+```
+
+---
+
+## elspais Configuration
+
+```toml
+# .elspais.toml
+
+[diagram]
+format = "plantuml"
+output_dir = "docs/diagrams"
+```
+
+---
+
+## Implementation Phase
+
+**Phase 3** (16-24 hours):
+
+1. Implement `elspais diagram` command
+2. Generate PlantUML from requirement hierarchy
+3. Include Type-based coloring/grouping
+4. Optionally parse PlantUML annotations back to requirements
+
+**Deliverables**:
+- PlantUML generation
+- Diagram templates
+- Integration documentation
+
+---
+
+## References
+
+- [PlantUML](https://plantuml.com/)
+- [C4 Model with PlantUML](https://c4model.com/)