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

elspais/{core/content_rules.py → content_rules.py}

@@ -1,14 +1,24 @@
 """
-elspais.core.content_rules - Content rule loading and parsing.
+elspais.content_rules - Content rule loading and parsing.
 
 Content rules are markdown files that provide semantic validation guidance
 for requirements authoring. They can include YAML frontmatter for metadata.
 """
 
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Dict, List, Tuple
 
-from elspais.core.models import ContentRule
+
+@dataclass
+class ContentRule:
+    """A content rule loaded from a markdown file."""
+
+    file_path: Path
+    title: str
+    content: str
+    type: str = "guidance"
+    applies_to: List[str] = field(default_factory=list)
 
 
 def parse_frontmatter(text: str) -> Tuple[Dict[str, Any], str]:
@@ -167,3 +177,11 @@ def load_content_rules(
                 pass
 
     return rules
+
+
+__all__ = [
+    "ContentRule",
+    "parse_frontmatter",
+    "load_content_rule",
+    "load_content_rules",
+]

elspais/docs/cli/assertions.md

@@ -0,0 +1,67 @@
+# WRITING ASSERTIONS
+
+## What is an Assertion?
+
+An assertion is a single, testable statement about system behavior.
+Each assertion:
+  - Uses **SHALL** or **SHALL NOT** (normative language)
+  - Is labeled A, B, C, etc.
+  - Can be independently verified by a test
+
+## Assertion Format
+
+```
+## Assertions
+
+A. The system SHALL authenticate users via email and password.
+B. The system SHALL lock accounts after 5 failed attempts.
+C. The system SHALL NOT store passwords in plain text.
+```
+
+## Normative Keywords
+
+  **SHALL**         Absolute requirement (must be implemented)
+  **SHALL NOT**     Absolute prohibition (must never happen)
+  **SHOULD**        Recommended but not required
+  **SHOULD NOT**    Not recommended but not prohibited
+  **MAY**           Optional behavior
+
+Most assertions use **SHALL** or **SHALL NOT**.
+
+## Good vs Bad Assertions
+
+**Good** (testable, specific):
+  A. The system SHALL respond to API requests within 200ms.
+  B. The system SHALL encrypt data at rest using AES-256.
+
+**Bad** (vague, untestable):
+  A. The system should be fast.
+  B. The system must be secure.
+
+## Referencing Assertions
+
+In implementing requirements:
+```
+**Implements**: REQ-p00001-A
+```
+
+In code comments:
+```
+# Implements: REQ-p00001-A
+```
+
+In tests:
+```python
+def test_login():
+    """REQ-p00001-A: Verify email/password auth"""
+```
+
+## Removed Assertions
+
+If you remove an assertion, keep a placeholder to maintain letter sequence:
+
+```
+A. The system SHALL do X.
+B. [Removed - superseded by REQ-d00005]
+C. The system SHALL do Z.
+```

elspais/docs/cli/commands.md

@@ -0,0 +1,304 @@
+# CLI COMMANDS REFERENCE
+
+Complete reference for all elspais commands.
+
+## Global Options
+
+These options work with all commands:
+
+  `-v, --verbose`    Verbose output with details
+  `-q, --quiet`      Suppress non-error output
+  `--config PATH`    Path to configuration file
+  `--spec-dir PATH`  Override spec directory
+
+## validate
+
+Validate requirements format, links, hashes, and hierarchy.
+
+  $ elspais validate                   # Check all rules
+  $ elspais validate --fix             # Auto-fix fixable issues
+  $ elspais validate --fix --dry-run   # Preview fixes
+  $ elspais validate -j                # Output JSON for tooling
+
+**Options:**
+
+  `--fix`               Auto-fix hashes and formatting issues
+  `--dry-run`           Preview fixes without modifying (use with --fix)
+  `--skip-rule RULE`    Skip validation rules (repeatable)
+  `-j, --json`          Output requirements as JSON
+
+**Skip Rule Patterns:**
+
+  `hash.*`        All hash rules
+  `hash.missing`  Hash footer is missing
+  `hash.mismatch` Hash doesn't match content
+  `hierarchy.*`   All hierarchy rules
+  `format.*`      All format rules
+
+## trace
+
+Generate traceability matrix and reports.
+
+  $ elspais trace --view          # Interactive HTML view
+  $ elspais trace --format html   # Basic HTML matrix
+  $ elspais trace --graph-json    # Export graph as JSON
+
+**Options:**
+
+  `--format {markdown,html,csv,both}`  Output format (default: both)
+  `--output PATH`          Output file path
+  `--view`                 Interactive HTML traceability tree
+  `--embed-content`        Embed full markdown in HTML for offline
+  `--graph`                Use unified traceability graph
+  `--graph-json`           Output graph structure as JSON
+  `--report NAME`          Report preset (minimal, standard, full)
+  `--depth LEVEL`          Max graph depth (0=roots, 1=children, ...)
+  `--mode {core,sponsor,combined}`  Report scope
+  `--sponsor NAME`         Sponsor name for filtered reports
+
+**Depth Levels:**
+
+  `0` or `requirements`    Show only requirements
+  `1` or `assertions`      Include assertions
+  `2` or `implementation`  Include code references
+  `full`                   Unlimited depth
+
+**Planned Options (not yet implemented):**
+
+  `--edit-mode`    In-browser editing of implements/status
+  `--review-mode`  Collaborative review with comments
+  `--server`       Start review server
+  `--port PORT`    Port for review server
+
+## hash
+
+Manage requirement content hashes.
+
+  $ elspais hash verify             # Check without changes
+  $ elspais hash update             # Update all stale hashes
+  $ elspais hash update REQ-p00001  # Update specific requirement
+  $ elspais hash update --dry-run   # Preview changes
+
+**Subcommands:**
+
+  `verify`            Verify hashes without modifying files
+  `update [REQ_ID]`   Update hashes (optionally for one requirement)
+
+**Options for update:**
+
+  `--dry-run`   Show changes without applying
+  `--json`      Output results as JSON for tooling
+
+## analyze
+
+Analyze requirement hierarchy and coverage.
+
+  $ elspais analyze hierarchy     # Tree view of requirements
+  $ elspais analyze orphans       # Find parentless requirements
+  $ elspais analyze coverage      # Implementation coverage report
+
+**Subcommands:**
+
+  `hierarchy`   Show requirement hierarchy tree
+  `orphans`     Find requirements with no parent
+  `coverage`    Implementation coverage report
+
+## changed
+
+Detect git changes to spec files.
+
+  $ elspais changed               # Show all spec changes
+  $ elspais changed -j            # Output as JSON
+  $ elspais changed -a            # Include non-spec files
+
+**Options:**
+
+  `--base-branch BRANCH`  Base branch for comparison (default: main)
+  `-j, --json`            Output as JSON
+  `-a, --all`             Include all changed files, not just spec
+
+**What's Detected:**
+
+  Uncommitted changes (modified/new spec files)
+  Changes vs main/master branch
+  Moved requirements (relocated to different file)
+
+## index
+
+Manage INDEX.md file.
+
+  $ elspais index validate       # Check accuracy
+  $ elspais index regenerate     # Rebuild from scratch
+
+**Subcommands:**
+
+  `validate`     Validate INDEX.md matches actual requirements
+  `regenerate`   Regenerate INDEX.md from current spec files
+
+## edit
+
+Edit requirements in-place.
+
+  $ elspais edit --req-id REQ-d00001 --status Draft
+  $ elspais edit --req-id REQ-d00001 --implements REQ-p00001,REQ-p00002
+  $ elspais edit --req-id REQ-d00001 --move-to roadmap/future.md
+  $ elspais edit --from-json edits.json
+
+**Options:**
+
+  `--req-id ID`         Requirement ID to edit
+  `--implements REFS`   New Implements (comma-separated, "" to clear)
+  `--status STATUS`     New Status value
+  `--move-to FILE`      Move to file (relative to spec dir)
+  `--from-json FILE`    Batch edit from JSON (- for stdin)
+  `--dry-run`           Show changes without applying
+  `--validate-refs`     Validate implements references exist
+
+**Batch JSON Format:**
+
+```json
+[
+  {"req_id": "REQ-d00001", "status": "Draft"},
+  {"req_id": "REQ-d00002", "implements": ["REQ-p00001"]}
+]
+```
+
+## config
+
+View and modify configuration.
+
+  $ elspais config show           # View all settings
+  $ elspais config get patterns.prefix
+  $ elspais config set project.name "MyApp"
+  $ elspais config path           # Show config file location
+
+**Subcommands:**
+
+  `show [--section] [-j]`  Show current configuration
+  `get KEY [-j]`           Get value (dot-notation: patterns.prefix)
+  `set KEY VALUE`          Set value (auto-detects type)
+  `unset KEY`              Remove a key
+  `add KEY VALUE`          Add value to array
+  `remove KEY VALUE`       Remove value from array
+  `path`                   Show config file location
+
+**Examples:**
+
+  $ elspais config get rules.strict_mode
+  $ elspais config set rules.strict_mode true
+  $ elspais config add directories.code src/lib
+  $ elspais config unset associated.prefix
+
+## init
+
+Create .elspais.toml configuration.
+
+  $ elspais init                  # Create default config
+  $ elspais init --template       # Also create example requirement
+
+**Options:**
+
+  `--type {core,associated}`   Repository type
+  `--associated-prefix PREFIX` Prefix for associated repo
+  `--force`                    Overwrite existing configuration
+  `--template`                 Create example requirement in spec/
+
+## example
+
+Display requirement format examples.
+
+  $ elspais example               # Quick format reference
+  $ elspais example --full        # Full specification document
+  $ elspais example journey       # User journey template
+
+**Arguments:**
+
+  `requirement`  Full requirement template (default)
+  `journey`      User journey template
+  `assertion`    Assertion rules and examples
+  `ids`          Show ID patterns from current config
+
+**Options:**
+
+  `--full`   Display full requirements specification file
+
+## rules
+
+View and manage content rules.
+
+  $ elspais rules list            # List configured rules
+  $ elspais rules show myfile.md  # Show rule file content
+
+**Subcommands:**
+
+  `list`        List configured content rules
+  `show FILE`   Show content of a rule file
+
+## docs
+
+Read the user guide.
+
+  $ elspais docs                  # Quickstart guide
+  $ elspais docs config           # Configuration reference
+  $ elspais docs all              # Complete documentation
+
+**Arguments:**
+
+  `quickstart`     Getting started guide (default)
+  `format`         Requirement file format
+  `hierarchy`      PRD/OPS/DEV levels
+  `assertions`     Writing testable assertions
+  `traceability`   Linking to code and tests
+  `validation`     Running validation
+  `git`            Change detection
+  `config`         Configuration reference
+  `commands`       This CLI reference
+  `mcp`            MCP server for AI integration
+  `all`            All topics concatenated
+
+**Options:**
+
+  `--plain`      Plain text output (no ANSI colors)
+  `--no-pager`   Disable paging (print to stdout)
+
+## completion
+
+Generate shell tab-completion scripts.
+
+  $ elspais completion            # Instructions
+  $ elspais completion --shell bash > ~/.elspais-complete.bash
+
+**Options:**
+
+  `--shell {bash,zsh,fish,tcsh}`  Generate for specific shell
+
+**Setup:**
+
+Bash: `source <(elspais completion --shell bash)`
+Zsh:  Add to ~/.zshrc: `eval "$(elspais completion --shell zsh)"`
+Fish: `elspais completion --shell fish | source`
+
+## version
+
+Show version information.
+
+  $ elspais version               # Show current version
+  $ elspais --version             # Alternative
+
+## mcp
+
+MCP (Model Context Protocol) server commands.
+
+  $ elspais mcp serve             # Start MCP server
+
+**Note:** Requires `elspais[mcp]` extra:
+
+  $ pip install 'elspais[mcp]'
+
+**Subcommands:**
+
+  `serve`   Start MCP server
+
+**Options for serve:**
+
+  `--transport {stdio,sse,streamable-http}`  Transport type (default: stdio)

elspais/docs/cli/config.md

@@ -0,0 +1,262 @@
+# CONFIGURATION
+
+## Configuration File
+
+elspais looks for `.elspais.toml` in the current directory
+or parent directories up to the git repository root.
+
+  $ elspais init          # Create default config
+  $ elspais config path   # Show config location
+  $ elspais config show   # View all settings
+
+## Complete Configuration Reference
+
+### [project] Section
+
+```toml
+[project]
+name = "my-project"        # Project name (optional)
+type = "core"              # "core" or "associated"
+```
+
+### [patterns] Section
+
+Controls requirement ID format and type definitions.
+
+```toml
+[patterns]
+id_template = "{prefix}-{type}{id}"   # ID template with tokens
+prefix = "REQ"                         # ID prefix
+
+# Type definitions (PRD, OPS, DEV levels)
+[patterns.types.prd]
+id = "p"           # Character in ID (REQ-p00001)
+name = "PRD"       # Display name
+level = 1          # Hierarchy level (1=highest)
+
+[patterns.types.ops]
+id = "o"
+name = "OPS"
+level = 2
+
+[patterns.types.dev]
+id = "d"
+name = "DEV"
+level = 3
+
+# ID number formatting
+[patterns.id_format]
+style = "numeric"      # Format style
+digits = 5             # Number of digits (0 = variable)
+leading_zeros = true   # Pad with zeros (00001 vs 1)
+```
+
+**Template Tokens:**
+  `{prefix}`     ID prefix (e.g., "REQ")
+  `{type}`       Type character (e.g., "p", "o", "d")
+  `{associated}` Associated repo prefix (if enabled)
+  `{id}`         Numeric ID
+
+### [patterns.associated] Section
+
+For multi-repository setups with associated requirement IDs.
+
+```toml
+[patterns.associated]
+enabled = true              # Enable associated repo IDs
+position = "after_prefix"   # Position in ID
+format = "uppercase"        # Format style
+length = 3                  # Prefix length
+separator = "-"             # Separator character
+```
+
+### [spec] Section
+
+Controls spec file discovery.
+
+```toml
+[spec]
+directories = ["spec"]      # Directories to scan
+patterns = ["*.md"]         # File patterns to include
+skip_files = ["README.md"]  # Files to skip
+skip_dirs = ["archive"]     # Subdirectories to skip
+index_file = "INDEX.md"     # Index file name
+
+# Map file patterns to levels (optional)
+[spec.file_patterns]
+"prd-*.md" = "prd"
+"ops-*.md" = "ops"
+"dev-*.md" = "dev"
+```
+
+### [directories] Section
+
+Override directory paths.
+
+```toml
+[directories]
+spec = "spec"               # Spec directory (string or array)
+code = ["src", "lib"]       # Code directories for traceability
+docs = "docs"               # Documentation directory
+ignore = ["node_modules"]   # Directories to ignore globally
+```
+
+### [rules] Section
+
+Validation and hierarchy rules.
+
+```toml
+[rules]
+strict_mode = false         # Strict implements semantics
+
+# Hierarchy relationship rules
+[rules.hierarchy]
+dev = ["ops", "prd"]        # DEV can implement OPS or PRD
+ops = ["prd"]               # OPS can implement PRD
+prd = []                    # PRD cannot implement anything
+
+# Alternative syntax (human-readable)
+allowed = [
+    "dev -> ops, prd",
+    "ops -> prd"
+]
+
+allow_circular = false      # Allow circular dependencies
+allow_orphans = false       # Allow requirements with no parent
+
+# Format validation rules
+[rules.format]
+require_hash = true         # Require hash footer
+require_rationale = false   # Require rationale section
+require_assertions = true   # Require assertions
+require_status = true       # Require status field
+allowed_statuses = [        # Valid status values
+    "Active",
+    "Draft",
+    "Deprecated",
+    "Superseded"
+]
+
+# Content rule modules (advanced)
+[rules.content_rules]
+modules = []                # Module paths for custom rules
+```
+
+### [validation] Section
+
+Hash and validation settings.
+
+```toml
+[validation]
+strict_hierarchy = true     # Strict hierarchy checking
+hash_algorithm = "sha256"   # Hash algorithm
+hash_length = 8             # Hash length in characters
+```
+
+### [traceability] Section
+
+Code and test scanning for traceability reports.
+
+```toml
+[traceability]
+output_formats = ["markdown", "html"]   # Default output formats
+output_dir = "."                         # Output directory
+
+# Code files to scan for implementations
+scan_patterns = [
+    "database/**/*.sql",
+    "src/**/*.py",
+    "apps/**/*.dart",
+]
+
+# Test result file locations
+test_results = [
+    "test-results/*.xml",    # JUnit XML
+    "pytest-report.json",    # pytest JSON
+]
+```
+
+### [associated] Section
+
+For associated (satellite) repositories.
+
+```toml
+[associated]
+prefix = "TTN"              # Associated repo prefix
+id_range = [1, 99999]       # ID range for this repo
+path = "../titan-spec"      # Path to associated repo
+```
+
+### [core] Section
+
+For associated repos referencing their core.
+
+```toml
+[core]
+path = "../core"            # Path to core repository
+```
+
+## Config Commands
+
+  $ elspais config show                # View all settings
+  $ elspais config show --section rules
+  $ elspais config show -j             # JSON output
+  $ elspais config get patterns.prefix
+  $ elspais config set project.name "NewName"
+  $ elspais config set rules.strict_mode true
+  $ elspais config unset rules.strict_mode
+  $ elspais config add directories.code src/lib
+  $ elspais config remove directories.code src/lib
+  $ elspais config path                # Show file location
+
+## Environment Variable Overrides
+
+Any config key can be overridden via environment variables:
+
+  ELSPAIS_PATTERNS_PREFIX=MYREQ elspais validate
+  ELSPAIS_RULES_STRICT_MODE=true elspais validate
+
+**Conversion:**
+  `ELSPAIS_PATTERNS_PREFIX` -> `patterns.prefix`
+  `ELSPAIS_RULES_STRICT_MODE` -> `rules.strict_mode`
+
+Rule: Remove `ELSPAIS_`, lowercase, underscores become dots.
+
+## Skip Directories
+
+Exclude directories from scanning:
+
+```toml
+[spec]
+skip_dirs = ["archive", "drafts"]
+
+[directories]
+ignore = ["node_modules", ".git"]
+```
+
+## Multi-Repository Setup
+
+**Core Repository (.elspais.toml):**
+
+```toml
+[project]
+name = "core-product"
+type = "core"
+
+[patterns]
+prefix = "REQ"
+```
+
+**Associated Repository (.elspais.toml):**
+
+```toml
+[project]
+name = "titan-extension"
+type = "associated"
+
+[associated]
+prefix = "TTN"
+
+[core]
+path = "../core-product"
+```