# abi-spec

Specification compiler with content-addressed SpecPacks, requirements traceability, and spec-driven development with drift detection. Part of the **Planning Pack (Layer 2)**.

Depends on `abi-control-core` for schema validation.

## Install (after PyPI publication)

```bash
pip install abi-spec
```

> **Status**: Not yet published to PyPI. Install from source: `pip install -e .` from the repo root. Requires `abi-control-core`.

## Quick start

### Compile a SpecPack from PRD JSON

```python
from abi_spec.compiler import compile_prd_json_to_specpack

# Compile a PRD JSON file into a content-addressed SpecPack
result = compile_prd_json_to_specpack(
    prd_json_path="runs/latest/prd.json",
    out_dir="specs/feature_x/",
)
print(result["manifest_hash"])  # SHA-256 of the spec manifest
print(result["prd_hash"])       # SHA-256 of the input PRD
```

### Spec-driven development with drift detection

```python
from pathlib import Path
from abi_spec.sdd.spec_tracker import SpecTracker

# Initialize tracker (stores metadata in .abi/ by default)
tracker = SpecTracker(tracking_dir=Path(".abi"))

# Track a spec and link it to implementing code paths
tracker.track(spec_path="specs/auth.md", code_paths=["src/auth/"])

# Detect drift between spec and code (time-based + hash-based)
drift = tracker.detect_drift(spec_path="specs/auth.md", code_paths=["src/auth/"])
if drift.has_drift:
    print(drift.details)  # e.g., "Code updated without spec update — drift detected"
```

### Requirements traceability

```python
from abi_spec.traceability import generate_requirements_index

# Generate a traceability index from structured requirements
requirements = [
    {
        "id": "REQ-001",
        "title": "User Authentication",
        "text": "System shall authenticate users",
        "acceptance": ["Given valid token, When request, Then access granted"],
        "source_prd_section": "Security.Authentication",
    },
]
index = generate_requirements_index(requirements)
# Returns list of dicts with req_id, title, acceptance_criteria, source_prd_section
```

## What's included

- **SpecPack compiler** -- compile PRD JSON into content-addressed, schema-validated specification packages
- **Requirements traceability** -- REQ-ID tracking with structured index generation
- **Acceptance criteria parsing** -- Given/When/Then extraction from structured requirements
- **Spec-driven development** -- `SpecTracker` with SHA-256 content hashing for drift detection
- **Drift detection** -- identify when specs and code are out of sync (time-based and hash-based)

## ABI ecosystem

`abi-spec` is part of the Planning Pack (Layer 2), built on top of `abi-control-core` (Layer 1).

Related packages:

- [abi-control-core](https://github.com/AbilityBI/abi-core) -- contracts and audit trail SDK (Layer 1, required)
- [abi-prd](https://github.com/AbilityBI/abi-prd) -- structured PRD generation (Layer 2)
- [abi-evals](https://github.com/AbilityBI/abi-evals) -- eval runner for validating spec compliance

## Versioning

Follows Semantic Versioning. Current version: `0.2.0`. See CHANGELOG.md for release notes.

## License

MIT License (see LICENSE file).
