iil-adrfw 0.2.0__tar.gz

iil_adrfw-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: python examples/test_e2e_schema_v3.py
+      - run: python examples/test_e2e.py
+      - run: python examples/test_e2e_v11.py
+      - run: python examples/test_e2e_regression.py

iil_adrfw-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Dry run (skip upload)"
+        required: false
+        default: "false"
+        type: choice
+        options:
+          - "true"
+          - "false"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install hatchling twine
+
+      - name: Build
+        run: python -m hatchling build
+
+      - name: Check dist
+        run: twine check dist/*
+
+      - name: Upload to PyPI
+        if: inputs.dry_run == 'false'
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

iil_adrfw-0.2.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.eggs/

iil_adrfw-0.2.0/.windsurf/rules/project-facts.md

@@ -0,0 +1,63 @@
+# Project Facts: iil-adrfw
+
+## Meta
+
+- **Type**: `python-library`
+- **GitHub**: `https://github.com/achimdehnert/iil-adrfw`
+- **Branch**: `main`
+- **PyPI**: `iil-adrfw`
+- **Build**: `hatchling` (`python3 -m hatchling build`)
+
+## Package
+
+| Field | Value |
+|-------|-------|
+| **Name** | `iil-adrfw` |
+| **Version** | `0.2.0` |
+| **Python** | `>=3.12` |
+| **Entry points** | `iil-adrfw` (CLI), `iil-adrfw-mcp` (FastMCP server) |
+| **Source layout** | `src/iil_adrfw/` |
+
+## Key modules
+
+| Module | Purpose |
+|--------|---------|
+| `persistence/` | Loader: normalize → validate → construct ADR objects |
+| `domain/` | ADR dataclass, Status enum, cross-repo models |
+| `graph/` | Constitution graph (supersession, dependencies) |
+| `audit/` | Staleness, implementation evidence checks |
+| `checkers/` | AST-based Python code checkers |
+| `cli.py` | CLI entry point |
+| `server.py` | FastMCP MCP server |
+
+## Schemas
+
+- `schemas/adr_frontmatter.schema.json` — ADR frontmatter (Schema v3)
+- `schemas/adr_rules.schema.json` — ADR executable rules
+- `schemas/constitution.schema.json` — Constitution graph
+
+## Tests
+
+```bash
+python3 examples/test_e2e_schema_v3.py   # 22 cases — Schema v3
+python3 examples/test_e2e.py              # Core tests
+python3 examples/test_e2e_v11.py          # v1.1 format tests
+python3 examples/test_e2e_regression.py   # Regression tests
+```
+
+## CI/CD
+
+- `.github/workflows/ci.yml` — ruff lint + test suites on push/PR
+- `.github/workflows/publish.yml` — hatchling build + twine upload (workflow_dispatch)
+
+## MCP Prefix (WSL Standard)
+
+| Prefix | Server |
+|--------|--------|
+| `mcp0_` | deployment-mcp |
+| `mcp1_` | github |
+| `mcp2_` | orchestrator |
+| `mcp3_` | outline-knowledge |
+| `mcp4_` | paperless-docs |
+| `mcp5_` | platform-context |
+| `mcp6_` | playwright |

iil_adrfw-0.2.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: iil-adrfw
+Version: 0.2.0
+Summary: Architectural Decision Record framework with bi-temporal validity, AST checkers, and FastMCP integration
+Project-URL: Homepage, https://github.com/achimdehnert/iil-adrfw
+Project-URL: Repository, https://github.com/achimdehnert/iil-adrfw
+Author-email: Achim Dehnert <achim@iil.gmbh>
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=3.0
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: libcst>=1.5
+Requires-Dist: pydantic>=2.8
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: referencing>=0.35
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# iil-adrfw
+
+**ADR Framework for the IIL Platform** — schema validation, loader normalization, constitution graph, audit tooling.
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## What it does
+
+- **Schema v3** — strict JSON Schema for ADR frontmatter with `additionalProperties: false`
+- **Phase 1 Normalizer** — 15+ field aliases, status normalization, type coercion, reference extraction
+- **Phase 2 Validator** — jsonschema validation against `adr_frontmatter.schema.json`
+- **Phase 3 Domain** — typed `ADR` dataclass with `Status` enum, temporal fields, relations
+- **Constitution Graph** — cross-ADR dependency/supersession graph with cycle detection
+- **Audit** — staleness checks, implementation evidence verification, drift detection
+- **CLI + MCP Server** — `iil-adrfw` CLI and `iil-adrfw-mcp` FastMCP server
+
+## Real-world validation
+
+Tested against **156 real platform ADRs**:
+
+| Mode | Result |
+|---|---|
+| Strict load (validate=True) | **152/156 (97.4%)** |
+| Unit tests | **22/22 green** |
+| Remaining failures | 4x broken YAML (unfixable) |
+
+## Installation
+
+```bash
+pip install -e .
+
+# With dev dependencies:
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Python API
+
+```python
+from pathlib import Path
+from iil_adrfw.persistence import load_adr, load_adrs
+
+# Load single ADR
+adr = load_adr(Path("docs/adr/ADR-099.md"), Path("schemas/"))
+
+# Load all ADRs in directory
+adrs = load_adrs(Path("docs/adr/"), Path("schemas/"))
+
+# Diagnosis mode (skip normalization)
+raw_adr = load_adr(path, schemas, raw=True)
+```
+
+### CLI
+
+```bash
+# Validate ADRs
+iil-adrfw validate docs/adr/ --schemas schemas/
+
+# Audit for staleness, missing evidence
+iil-adrfw audit docs/adr/ --schemas schemas/
+```
+
+### MCP Server
+
+```bash
+iil-adrfw-mcp
+```
+
+## Schema v3 highlights
+
+- **5 new fields**: `updated`, `version`, `review_status`, `owner`, `implementation_done_when`
+- **3 removed fields**: `glossary`, `review_cadence`, `next_review_date`
+- **Status enum**: `{draft, proposed, accepted, deprecated, superseded, rejected, experimental}`
+- **Implementation status**: `{none, planned, in_progress, partial, implemented, complete, verified, rolled_back}`
+
+### Loader normalizations (Phase 1)
+
+| Step | What |
+|---|---|
+| C.1 | 12 field aliases (`date`→`decision_date`, `author`→`owner`, etc.) |
+| C.2 | Status normalization (case, suffixes) |
+| C.3 | Scalar-to-list auto-wrapping |
+| C.4 | Reference field normalization (ADR-NNN extraction) |
+| C.5 | ID inference, title inference, domains default, deciders default |
+| C.6 | Amended-format normalization |
+| C.7 | `implemented` field → `implementation_status` mapping |
+| C.8 | Strip unknown properties |
+
+See [SCHEMA_V3_SPEC.md](SCHEMA_V3_SPEC.md) for full specification.
+
+## Running tests
+
+```bash
+python examples/test_e2e_schema_v3.py   # Schema v3 tests (22 cases)
+python examples/test_e2e.py              # Core tests
+python examples/test_e2e_v11.py          # v1.1 format tests
+```
+
+## Project structure
+
+```
+iil-adrfw/
+├── schemas/                    # JSON Schema files
+│   ├── adr_frontmatter.schema.json
+│   ├── adr_rules.schema.json
+│   └── constitution.schema.json
+├── src/iil_adrfw/
+│   ├── persistence/            # Loader (normalize + validate + construct)
+│   ├── domain/                 # ADR dataclass, Status enum
+│   ├── graph/                  # Constitution graph
+│   ├── audit/                  # Staleness, evidence checks
+│   ├── checkers/               # AST-based code checkers
+│   ├── cli.py                  # CLI entry point
+│   └── server.py               # FastMCP server
+├── examples/                   # Example ADRs + test suites
+├── SCHEMA_V3_SPEC.md          # Full v3 specification
+└── SCHEMA_V3_CHANGELOG.md     # Changelog for downstream consumers
+```

iil_adrfw-0.2.0/README.md

@@ -0,0 +1,120 @@
+# iil-adrfw
+
+**ADR Framework for the IIL Platform** — schema validation, loader normalization, constitution graph, audit tooling.
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## What it does
+
+- **Schema v3** — strict JSON Schema for ADR frontmatter with `additionalProperties: false`
+- **Phase 1 Normalizer** — 15+ field aliases, status normalization, type coercion, reference extraction
+- **Phase 2 Validator** — jsonschema validation against `adr_frontmatter.schema.json`
+- **Phase 3 Domain** — typed `ADR` dataclass with `Status` enum, temporal fields, relations
+- **Constitution Graph** — cross-ADR dependency/supersession graph with cycle detection
+- **Audit** — staleness checks, implementation evidence verification, drift detection
+- **CLI + MCP Server** — `iil-adrfw` CLI and `iil-adrfw-mcp` FastMCP server
+
+## Real-world validation
+
+Tested against **156 real platform ADRs**:
+
+| Mode | Result |
+|---|---|
+| Strict load (validate=True) | **152/156 (97.4%)** |
+| Unit tests | **22/22 green** |
+| Remaining failures | 4x broken YAML (unfixable) |
+
+## Installation
+
+```bash
+pip install -e .
+
+# With dev dependencies:
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Python API
+
+```python
+from pathlib import Path
+from iil_adrfw.persistence import load_adr, load_adrs
+
+# Load single ADR
+adr = load_adr(Path("docs/adr/ADR-099.md"), Path("schemas/"))
+
+# Load all ADRs in directory
+adrs = load_adrs(Path("docs/adr/"), Path("schemas/"))
+
+# Diagnosis mode (skip normalization)
+raw_adr = load_adr(path, schemas, raw=True)
+```
+
+### CLI
+
+```bash
+# Validate ADRs
+iil-adrfw validate docs/adr/ --schemas schemas/
+
+# Audit for staleness, missing evidence
+iil-adrfw audit docs/adr/ --schemas schemas/
+```
+
+### MCP Server
+
+```bash
+iil-adrfw-mcp
+```
+
+## Schema v3 highlights
+
+- **5 new fields**: `updated`, `version`, `review_status`, `owner`, `implementation_done_when`
+- **3 removed fields**: `glossary`, `review_cadence`, `next_review_date`
+- **Status enum**: `{draft, proposed, accepted, deprecated, superseded, rejected, experimental}`
+- **Implementation status**: `{none, planned, in_progress, partial, implemented, complete, verified, rolled_back}`
+
+### Loader normalizations (Phase 1)
+
+| Step | What |
+|---|---|
+| C.1 | 12 field aliases (`date`→`decision_date`, `author`→`owner`, etc.) |
+| C.2 | Status normalization (case, suffixes) |
+| C.3 | Scalar-to-list auto-wrapping |
+| C.4 | Reference field normalization (ADR-NNN extraction) |
+| C.5 | ID inference, title inference, domains default, deciders default |
+| C.6 | Amended-format normalization |
+| C.7 | `implemented` field → `implementation_status` mapping |
+| C.8 | Strip unknown properties |
+
+See [SCHEMA_V3_SPEC.md](SCHEMA_V3_SPEC.md) for full specification.
+
+## Running tests
+
+```bash
+python examples/test_e2e_schema_v3.py   # Schema v3 tests (22 cases)
+python examples/test_e2e.py              # Core tests
+python examples/test_e2e_v11.py          # v1.1 format tests
+```
+
+## Project structure
+
+```
+iil-adrfw/
+├── schemas/                    # JSON Schema files
+│   ├── adr_frontmatter.schema.json
+│   ├── adr_rules.schema.json
+│   └── constitution.schema.json
+├── src/iil_adrfw/
+│   ├── persistence/            # Loader (normalize + validate + construct)
+│   ├── domain/                 # ADR dataclass, Status enum
+│   ├── graph/                  # Constitution graph
+│   ├── audit/                  # Staleness, evidence checks
+│   ├── checkers/               # AST-based code checkers
+│   ├── cli.py                  # CLI entry point
+│   └── server.py               # FastMCP server
+├── examples/                   # Example ADRs + test suites
+├── SCHEMA_V3_SPEC.md          # Full v3 specification
+└── SCHEMA_V3_CHANGELOG.md     # Changelog for downstream consumers
+```

iil_adrfw-0.2.0/SCHEMA_V3_CHANGELOG.md

@@ -0,0 +1,146 @@
+# Schema v3 — Changelog
+
+**Date:** 2026-05-08
+**Basis:** Real-world data on 156 platform ADRs (Cascade run)
+**Goal:** Lift strict-load rate from 65% (102/156) to ≥97% via schema additions
+and Phase 1 normalization.
+
+---
+
+## Schema additions (5 fields truly new, all optional)
+
+| Field | Type | Real-world frequency |
+|---|---|---|
+| `updated` | string (date) | 5% |
+| `version` | integer ≥1 | 3% |
+| `review_status` | enum (`pending`, `in_review`, `approved`, `rejected`, `stale`) | 3% |
+| `owner` | string | 1% direct + receives `author` alias mappings |
+| `implementation_done_when` | string | 1% |
+
+Note: `implementation_evidence`, `related`, `amends` were already in v2 schema.
+
+## Schema removals (3 fields, 0% real-world use)
+
+- `glossary` — content belongs in markdown body (see ADR-188 v1.1 example)
+- `review_cadence` — replaced functionally by `staleness_months`
+- `next_review_date` — was a derived field, never populated
+
+## Schema unchanged (critical for backwards compatibility)
+
+- **Status enum** — `{draft, proposed, accepted, deprecated, superseded, rejected, experimental}` — `draft` used by 2 ADRs
+- **`implementation_status` enum** — `{none, planned, in_progress, partial, implemented, complete, verified, rolled_back}` — `implemented` used by 81 ADRs, `verified` by 1
+- **`additionalProperties: false`** — strict mode retained for governance
+- **All v1.1 strategic fields** — `decision_drivers`, `open_questions`, `consumers`, `deprecation_timeline`, `spof_mitigation`, `per_repo_status` — kept as the v1.1 reference format
+
+---
+
+## Loader behavior (Phase 1 normalization)
+
+All Phase 1 transforms run by default. To bypass them for diagnostic purposes:
+`load_adr(path, schemas, raw=True)`.
+
+### Field aliases (target wins if both present)
+
+| Source | Target |
+|---|---|
+| `decision-makers` | `deciders` |
+| `superseded-by` | `superseded_by` |
+| `depends-on` | `depends_on` |
+| `conflicts-with` | `conflicts_with` |
+| `relates_to`, `relates-to`, `related_adrs` | `related` |
+| `last_verified` | `last_reviewed` |
+| `adr_id` | `id` |
+| `review` | `review_status` |
+| `author` | `owner` |
+
+### Stripped fields (low-frequency tool-noise)
+
+`reviewed-by`, `reviewed`, `repos`, `nav_order`, `parent`, `commit`,
+`product_name`, `supersedes_check`, `superseded_by_planned`
+
+### Status normalization
+
+Applied to the `status` value:
+- Case-insensitive: `Accepted` → `accepted`
+- Strip quotes: `'"accepted"'` → `accepted`
+- Strip version suffix: `accepted (v2)` → `accepted`
+- Strip revision suffix: `Accepted (Revision v1.1)` → `accepted`
+
+Unknown values pass through unchanged so the schema enum check produces a
+clear error message.
+
+### Auto-wrap scalar-to-list (only on observed-as-scalar fields)
+
+`deciders`, `consulted`, `informed`, `domains`, `amends` — string value gets
+wrapped to `[value]`. Sentinel values `–`, `-`, `—`, `n/a`, `none`, `""` →
+empty list `[]`.
+
+### Reference-field normalization
+
+For `supersedes`, `superseded_by`, `depends_on`, `consolidates`,
+`conflicts_with`, `informs`, `related`, `amends`: strings have all
+`ADR-NNN` tokens extracted into a list.
+
+### `implemented` field handling
+
+| Input | Action |
+|---|---|
+| `implemented: true` | set `implementation_status: implemented` |
+| `implemented: "2026-03-15"` (date) | set `implementation_status: implemented` AND `updated: "2026-03-15"` |
+| `implemented: false` | leave `implementation_status` unchanged |
+
+The field is always removed from the frontmatter after processing.
+
+### Amended-format normalization
+
+Legacy form `amended: "2026-05-08"` (plain date) is recognized:
+- The date is moved to `last_reviewed` (if not already set)
+- The malformed `amended` field is dropped
+
+Proper `amended` lists (with `version`, `at`, `by`, `summary`) pass through unchanged.
+
+### Title inference
+
+If `title` is missing or empty:
+1. Try first H1 in body: `# ADR-NNN — <title>` or `# ADR-NNN: <title>`
+2. Fallback: filename slug `ADR-098-multi-tenant-cron.md` → `"multi tenant cron"`
+3. Final fallback: `"(untitled ADR)"`
+
+---
+
+## Migration impact
+
+- **Existing ADR files:** No file rewrites needed. Phase 1 normalization handles
+  legacy formats transparently.
+- **Existing tests:** All 41 prior tests remain green.
+- **adr-doctor compatibility:** unchanged — both tools share normalization
+  semantics but operate independently.
+
+## API change: `raw` parameter
+
+```python
+# Before v3 (still supported):
+load_adr(path, schemas, validate=True)
+load_adr(path, schemas, validate=False)
+
+# New in v3 — diagnostic mode:
+load_adr(path, schemas, validate=False, raw=True)  # see frontmatter as-written
+```
+
+`raw=True` skips Phase 1 entirely. Useful for finding ADRs that depend on
+tolerance and could be migrated to canonical form.
+
+## Test additions
+
+- `test_e2e_schema_v3.py` — 22 tests covering all C.1–C.8 transforms,
+  field renames, schema additions/removals, and combined real-world scenarios.
+
+## Out of scope for v3
+
+| Topic | Why deferred |
+|---|---|
+| `nav_order`, `parent`, `commit`, `product_name` as schema fields | <2% use, stripped instead |
+| `reviewed-by` as own field | 1% use, semantically distinct from `consulted`, stripped |
+| Audit auditors using new fields (`implementation_evidence_check`, `circular_dependency`, `orphaned_adr`) | Iter 3 — separate increment |
+| Schema `$id` version bump | Cosmetic, deferred to first breaking change |
+| Status aliases (`done`, `active`, `wip`) | Antizipativ, nicht in echten Daten beobachtet — log-warning instead |