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

elspais/docs/cli/format.md

@@ -0,0 +1,66 @@
+# REQUIREMENT FORMAT REFERENCE
+
+## File Structure
+
+Requirements are Markdown files in `spec/`. Each file can contain
+one or more requirements separated by `---` (horizontal rule).
+
+Naming convention: `spec/<level>-<topic>.md`
+  Examples: `spec/prd-auth.md`, `spec/dev-api.md`
+
+## Requirement Structure
+
+```
+# REQ-p00001: Human-Readable Title
+
+**Level**: PRD | **Status**: Active | **Implements**: none
+
+**Purpose:** One-line description of why this requirement exists.
+
+## Assertions
+
+A. The system SHALL do something specific and testable.
+B. The system SHALL NOT do something prohibited.
+
+*End* *Human-Readable Title* | **Hash**: a1b2c3d4
+```
+
+## ID Format
+
+  **REQ-<type><number>**
+
+  Types:
+    `p` = PRD (Product)     e.g., REQ-p00001
+    `o` = OPS (Operations)  e.g., REQ-o00001
+    `d` = DEV (Development) e.g., REQ-d00001
+
+  The shorthand `p00001` can be used in displays (without REQ- prefix).
+
+## Header Line Fields
+
+  **Level**:      PRD, OPS, or DEV (determines hierarchy position)
+  **Status**:     Active, Draft, Deprecated, or Proposed
+  **Implements**: Parent requirement ID(s), comma-separated
+  **Refines**:    Parent ID when adding detail without claiming coverage
+
+## Hash
+
+The 8-character hash is computed from the requirement body content.
+When content changes, the hash changes, triggering review.
+
+  $ elspais hash update   # Recompute all hashes
+  $ elspais hash verify   # Check for stale hashes
+
+## Multiple Requirements Per File
+
+Separate requirements with a horizontal rule:
+
+```
+# REQ-p00001: First Requirement
+...
+*End* *First Requirement* | **Hash**: ...
+
+---
+# REQ-p00002: Second Requirement
+...
+```

elspais/docs/cli/git.md

@@ -0,0 +1,45 @@
+# GIT INTEGRATION
+
+## Detecting Changes
+
+  $ elspais changed              # Show all spec changes
+  $ elspais changed -j           # Output as JSON
+  $ elspais changed -a           # Include non-spec files
+  $ elspais changed --base-branch develop  # Compare to different branch
+
+## Command Options
+
+  `--base-branch BRANCH`  Base branch for comparison (default: main)
+  `-j, --json`            Output as JSON for tooling
+  `-a, --all`             Include all changed files (not just spec)
+
+## What 'Changed' Detects
+
+  **Uncommitted** - Modified/untracked spec files
+  **Hash mismatch** - Content changed but hash not updated
+  **Moved** - Requirement relocated to different file
+  **vs Main** - Changes compared to main/master branch
+
+## In Trace View
+
+The interactive trace view (`elspais trace --view`) shows:
+
+  **◆** Changed vs main branch (diamond indicator)
+  Filter buttons: `[Uncommitted]` `[Changed vs Main]`
+
+## Pre-Commit Hook Example
+
+```sh
+#!/bin/sh
+# .git/hooks/pre-commit
+elspais validate || exit 1
+elspais hash verify || echo "Warning: stale hashes"
+```
+
+## Workflow
+
+1. Edit requirements
+2. $ elspais validate  # Check format
+3. $ elspais hash update  # Update hashes
+4. $ elspais changed  # Review what changed
+5. Commit with message referencing requirement IDs

elspais/docs/cli/health.md

@@ -0,0 +1,190 @@
+# Health Check Command
+
+The `elspais health` command diagnoses configuration and repository issues, helping you identify problems before they affect your workflow.
+
+## Quick Start
+
+```bash
+# Run all health checks
+elspais health
+
+# Check specific category only
+elspais health --config    # Configuration checks
+elspais health --spec      # Spec file checks
+elspais health --code      # Code reference checks
+elspais health --tests     # Test mapping checks
+```
+
+## Check Categories
+
+### Configuration Checks (`--config`)
+
+| Check | Description |
+|-------|-------------|
+| `config.exists` | Verifies config file exists or using defaults |
+| `config.syntax` | Validates TOML syntax is correct |
+| `config.required_fields` | Ensures required sections present |
+| `config.pattern_tokens` | Validates pattern template tokens |
+| `config.hierarchy_rules` | Checks hierarchy rules consistency |
+| `config.paths_exist` | Verifies spec directories exist |
+
+### Spec File Checks (`--spec`)
+
+| Check | Description |
+|-------|-------------|
+| `spec.parseable` | All spec files can be parsed |
+| `spec.no_duplicates` | No duplicate requirement IDs |
+| `spec.implements_resolve` | All Implements: references resolve |
+| `spec.refines_resolve` | All Refines: references resolve |
+| `spec.hierarchy_levels` | Requirements follow hierarchy rules |
+| `spec.orphans` | No orphan requirements (non-PRD without parents) |
+
+### Code Reference Checks (`--code`)
+
+| Check | Description |
+|-------|-------------|
+| `code.references_resolve` | Code `# Implements:` comments resolve |
+| `code.coverage` | Code coverage statistics (informational) |
+
+### Test Mapping Checks (`--tests`)
+
+| Check | Description |
+|-------|-------------|
+| `tests.references_resolve` | Test REQ references resolve |
+| `tests.results` | Test pass/fail status from results |
+| `tests.coverage` | Test coverage statistics (informational) |
+
+## Output Formats
+
+### Text Output (default)
+
+```
+✓ CONFIG (6/6 checks passed)
+----------------------------------------
+  ✓ config.exists: Config file found: .elspais.toml
+  ✓ config.syntax: TOML syntax is valid
+  ✓ config.required_fields: All required configuration fields present
+  ✓ config.pattern_tokens: Pattern template valid: {prefix}-{type}{id}
+  ✓ config.hierarchy_rules: Hierarchy rules valid (3 levels configured)
+  ✓ config.paths_exist: All spec directories exist (1 found)
+
+✓ SPEC (6/6 checks passed)
+----------------------------------------
+  ✓ spec.parseable: Parsed 42 requirements with 128 assertions
+  ✓ spec.no_duplicates: No duplicate requirement IDs
+  ✓ spec.implements_resolve: All Implements references resolve
+  ✓ spec.refines_resolve: All Refines references resolve
+  ✓ spec.hierarchy_levels: All requirements follow hierarchy rules
+  ✓ spec.orphans: No orphan requirements
+
+========================================
+✓ HEALTHY: 12 checks passed
+========================================
+```
+
+### JSON Output (`-j` or `--json`)
+
+```json
+{
+  "healthy": true,
+  "summary": {
+    "passed": 12,
+    "failed": 0,
+    "warnings": 0
+  },
+  "checks": [
+    {
+      "name": "config.exists",
+      "passed": true,
+      "message": "Config file found: .elspais.toml",
+      "category": "config",
+      "severity": "error",
+      "details": {"path": ".elspais.toml"}
+    }
+  ]
+}
+```
+
+## Command Options
+
+| Option | Description |
+|--------|-------------|
+| `--config` | Run configuration checks only |
+| `--spec` | Run spec file checks only |
+| `--code` | Run code reference checks only |
+| `--tests` | Run test mapping checks only |
+| `-j`, `--json` | Output as JSON |
+| `-v`, `--verbose` | Show additional details |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All checks passed (healthy) |
+| 1 | One or more errors found |
+
+Warnings do not affect the exit code - only errors cause a non-zero exit.
+
+## Severity Levels
+
+- **error**: Critical issue that should be fixed
+- **warning**: Issue that may indicate a problem
+- **info**: Informational (e.g., coverage statistics)
+
+## Use Cases
+
+### CI/CD Pipeline Check
+
+```bash
+# Fail pipeline if health checks fail
+elspais health || exit 1
+```
+
+### Quick Config Validation
+
+```bash
+# Just check config before making changes
+elspais health --config
+```
+
+### Debugging Reference Issues
+
+```bash
+# Verbose output for debugging
+elspais health --spec -v
+```
+
+### JSON Processing
+
+```bash
+# Get failed checks in CI
+elspais health -j | jq '.checks | map(select(.passed == false))'
+```
+
+## Troubleshooting
+
+### "No requirements found"
+
+This usually means:
+- The spec directory doesn't exist
+- No `.md` files in the spec directory
+- Files don't contain valid requirement format
+
+Run with verbose to see details:
+```bash
+elspais health --spec -v
+```
+
+### "Unresolved Implements references"
+
+A requirement references another that doesn't exist:
+1. Check for typos in the requirement ID
+2. Ensure the parent requirement exists
+3. Check if using assertion syntax (e.g., `REQ-xxx-A`)
+
+### "TOML syntax error"
+
+Your `.elspais.toml` has invalid syntax:
+1. Check for unclosed quotes or brackets
+2. Validate with a TOML linter
+3. Compare against the default config structure

elspais/docs/cli/hierarchy.md

@@ -0,0 +1,60 @@
+# REQUIREMENT HIERARCHY
+
+## The Three Levels
+
+elspais enforces a **PRD -> OPS -> DEV** hierarchy:
+
+  **PRD (Product)**    - Business needs, user outcomes
+                     "What the product must achieve"
+
+  **OPS (Operations)** - Operational constraints, compliance
+                     "How the system must behave operationally"
+
+  **DEV (Development)** - Technical specifications
+                     "How we implement it technically"
+
+## Implements Relationships
+
+Lower levels **implement** higher levels:
+
+  DEV -> OPS   (DEV implements OPS)
+  DEV -> PRD   (DEV implements PRD)
+  OPS -> PRD   (OPS implements PRD)
+
+**Never** the reverse: PRD cannot implement DEV.
+
+Example chain:
+
+  `REQ-p00001`: Users can reset passwords (PRD)
+       ^
+  `REQ-o00001`: Reset tokens expire in 1 hour (OPS)
+       ^           Implements: REQ-p00001
+  `REQ-d00001`: Tokens use HMAC-SHA256 (DEV)
+                   Implements: REQ-o00001
+
+## Implements vs Refines
+
+  **Implements** - Claims to satisfy the parent requirement
+               Coverage rolls up in traceability reports
+
+  **Refines**    - Adds detail to parent without claiming satisfaction
+               No coverage rollup; just shows relationship
+
+Use `Refines` when you're adding constraints but the parent still
+needs its own implementation.
+
+## Assertion-Specific Implementation
+
+Implement specific assertions, not the whole requirement:
+
+```
+**Implements**: REQ-p00001-A    # Just assertion A
+**Implements**: REQ-p00001-A-B  # Assertions A and B
+```
+
+This gives precise traceability coverage.
+
+## Viewing the Hierarchy
+
+  $ elspais analyze hierarchy  # ASCII tree view
+  $ elspais trace --view       # Interactive HTML

elspais/docs/cli/ignore.md

@@ -0,0 +1,72 @@
+# Ignore Configuration
+
+The `[ignore]` section in `.elspais.toml` controls which files are skipped during scanning.
+
+## Pattern Syntax
+
+Patterns use Python's `fnmatch` module (similar to shell globs).
+
+**Important**: Patterns match from the START of the path, not anywhere. This differs from gitignore behavior.
+
+## Pattern Characters
+
+- `*` matches any characters within a path component
+- `**` matches across directory separators
+- `?` matches a single character
+
+## Examples
+
+```toml
+[ignore]
+# Skip files named "README.md" or "INDEX.md" (basename match)
+spec = ["README.md", "INDEX.md"]
+
+# Skip a directory at any depth - use **/ prefix
+spec = ["**/roadmap/**"]
+
+# Skip a specific path from repo root
+spec = ["spec/archive/**"]
+
+# Skip by extension (anywhere)
+global = ["*.pyc", "*.tmp"]
+```
+
+## Common Patterns
+
+| Goal | Pattern | Example Match |
+|------|---------|---------------|
+| Skip directory anywhere | `**/dirname/**` | `spec/dirname/file.md` |
+| Skip specific path | `spec/archive/**` | `spec/archive/old.md` |
+| Skip by filename | `README.md` | `spec/README.md` |
+| Skip by extension | `*.pyc` | `src/__pycache__/foo.pyc` |
+
+## Scopes
+
+Each scope applies to a specific scanning context:
+
+| Scope | When Applied |
+|-------|--------------|
+| `global` | All scanning operations |
+| `spec` | Scanning spec directories for requirements |
+| `code` | Scanning code directories for `# Implements:` references |
+| `test` | Scanning test directories for REQ references |
+
+## Default Patterns
+
+```toml
+[ignore]
+global = ["node_modules", ".git", "__pycache__", "*.pyc", ".venv", ".env"]
+spec = ["README.md", "INDEX.md"]
+code = ["*_test.py", "conftest.py", "test_*.py"]
+test = ["fixtures/**", "__snapshots__"]
+```
+
+## Migration from gitignore-style Patterns
+
+If you're used to gitignore patterns, note these differences:
+
+| gitignore | elspais [ignore] | Notes |
+|-----------|------------------|-------|
+| `roadmap/` | `**/roadmap/**` | Must use `**/` for "anywhere" |
+| `/roadmap/` | `roadmap/**` | Leading `/` not needed (already anchored) |
+| `*.md` | `*.md` | Same behavior for extensions |

elspais/docs/cli/mcp.md

@@ -0,0 +1,245 @@
+# MCP SERVER
+
+Model Context Protocol (MCP) server for AI-driven requirements management.
+
+## Overview
+
+The elspais MCP server exposes the requirements graph to AI assistants,
+enabling intelligent requirement navigation, search, and analysis without
+manual CLI usage.
+
+**Installation:**
+
+  $ pip install 'elspais[mcp]'
+
+**Starting the server:**
+
+  $ elspais mcp serve
+  $ python -m elspais.mcp
+
+## Available Tools
+
+### Graph Status & Control
+
+**get_graph_status()**
+
+Get current graph health and statistics.
+
+  Returns:
+    root_count        Number of root requirements
+    node_counts       Count by node kind (requirement, assertion, code, test)
+    total_nodes       Total nodes in graph
+    has_orphans       Whether orphaned nodes exist
+    has_broken_references  Whether broken references exist
+
+  Example response:
+    {
+      "root_count": 3,
+      "node_counts": {"requirement": 45, "assertion": 120, "code": 30},
+      "total_nodes": 195,
+      "has_orphans": false,
+      "has_broken_references": false
+    }
+
+**refresh_graph(full)**
+
+Force rebuild the graph from spec files.
+
+  Parameters:
+    full (bool)   If true, clear all caches before rebuild
+
+  Returns:
+    success       Whether rebuild succeeded
+    message       Status message
+    node_count    New total node count
+
+### Requirement Search & Navigation
+
+**search(query, field, regex, limit)**
+
+Search requirements by ID, title, or content.
+
+  Parameters:
+    query (str)     Search string or regex pattern
+    field (str)     Field to search: 'id', 'title', 'body', or 'all' (default)
+    regex (bool)    If true, treat query as regex pattern (default: false)
+    limit (int)     Maximum results to return (default: 50)
+
+  Returns:
+    List of matching requirement summaries with id, title, level, status.
+
+  Examples:
+    search("authentication")           # Find auth-related requirements
+    search("REQ-p", field="id")        # Find PRD-level by ID prefix
+    search(".*security.*", regex=true) # Regex search in all fields
+
+**get_requirement(req_id)**
+
+Get full details for a single requirement.
+
+  Parameters:
+    req_id (str)    The requirement ID (e.g., 'REQ-p00001')
+
+  Returns:
+    id              Requirement ID
+    title           Requirement title
+    level           PRD, OPS, or DEV
+    status          Draft, Active, Deprecated, etc.
+    hash            Content hash for change detection
+    assertions      List of assertion objects {id, label, text}
+    children        Child requirements (summaries)
+    parents         Parent requirements (summaries)
+
+  Example:
+    get_requirement("REQ-p00001")
+
+**get_hierarchy(req_id)**
+
+Get requirement hierarchy (ancestors and children).
+
+  Parameters:
+    req_id (str)    The requirement ID
+
+  Returns:
+    id              The queried requirement ID
+    ancestors       All ancestor requirements (walks to roots)
+    children        Direct child requirements
+
+  Use this to understand where a requirement sits in the hierarchy
+  and what depends on it.
+
+### Workspace Context
+
+**get_workspace_info()**
+
+Get information about the current workspace/repository.
+
+  Returns:
+    repo_path       Absolute path to repository root
+    project_name    Project name from config or directory name
+    config_file     Path to .elspais.toml (if exists)
+    config_summary  Key configuration values:
+      - prefix          Requirement ID prefix
+      - spec_directories  Where spec files live
+      - testing_enabled   Whether test scanning is on
+      - project_type      'core' or 'associated'
+
+**get_project_summary()**
+
+Get summary statistics for the project.
+
+  Returns:
+    requirements_by_level   Count by PRD/OPS/DEV level
+    coverage                Coverage statistics:
+      - full              Requirements with full coverage
+      - partial           Requirements with partial coverage
+      - none              Requirements with no coverage
+    changes                 Git change metrics:
+      - uncommitted       Modified spec files
+      - branch_changed    Changed vs main branch
+    total_nodes            Total nodes in graph
+    orphan_count           Requirements without parents
+    broken_reference_count References to non-existent requirements
+
+## Client Configuration
+
+### Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "elspais": {
+      "type": "stdio",
+      "command": "elspais",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+Or with explicit Python path:
+
+```json
+{
+  "mcpServers": {
+    "elspais": {
+      "type": "stdio",
+      "command": "python",
+      "args": ["-m", "elspais.mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to Cursor's MCP settings:
+
+```json
+{
+  "elspais": {
+    "command": "elspais",
+    "args": ["mcp", "serve"]
+  }
+}
+```
+
+## Transport Options
+
+  stdio (default)   Standard input/output, best for local tools
+  sse               Server-sent events, for HTTP clients
+  streamable-http   HTTP streaming, for web clients
+
+  $ elspais mcp serve --transport stdio
+  $ elspais mcp serve --transport sse
+
+## Typical Workflows
+
+### Understanding a Requirement
+
+1. `get_requirement("REQ-p00001")` - Get full details
+2. `get_hierarchy("REQ-p00001")` - See where it fits
+3. Check assertions for testable criteria
+
+### Finding Related Requirements
+
+1. `search("authentication")` - Find by keyword
+2. `get_hierarchy(result_id)` - Navigate relationships
+3. Follow children to see implementations
+
+### Project Health Check
+
+1. `get_graph_status()` - Check for orphans/broken refs
+2. `get_project_summary()` - Review coverage stats
+3. Address requirements with `coverage: none`
+
+### After Editing Spec Files
+
+1. `refresh_graph()` - Rebuild after changes
+2. `get_graph_status()` - Verify graph health
+
+## Configuration Notes
+
+The exact requirement ID syntax (prefixes, patterns) and hierarchy rules are
+**configurable per project** via `.elspais.toml`. Different projects may use:
+
+- Different ID prefixes (e.g., `REQ-`, `SPEC-`, `FR-`)
+- Different level types (PRD/OPS/DEV or custom)
+- Different hierarchy rules for "implements" relationships
+
+Use `get_workspace_info()` to see the current project's configuration.
+
+## Architecture Notes
+
+The MCP server is a **pure interface layer** that consumes the TraceGraph
+directly without creating intermediate data structures. This ensures:
+
+- Single source of truth (the graph)
+- No data duplication or caching issues
+- Consistent results across all tools
+- Efficient memory usage
+
+All tools use the iterator-only API (`iter_children()`, `iter_parents()`,
+`nodes_by_kind()`) to prevent accidental list materialization on large graphs.