Metadata-Version: 2.4
Name: svl-cli
Version: 2.0.0
Summary: Sovereignty by Deliverable — a static gate for agentic-system specifications. Checks owner, deliverable, projection contract, audit trace.
Author-email: Guillaume Aubry <guillaume@hestia-projekt.com>
License: MIT
Project-URL: Homepage, https://github.com/guillaume-hestia-projekt/svl
Project-URL: Documentation, https://github.com/guillaume-hestia-projekt/svl#readme
Project-URL: Repository, https://github.com/guillaume-hestia-projekt/svl
Project-URL: Issues, https://github.com/guillaume-hestia-projekt/svl/issues
Project-URL: Changelog, https://github.com/guillaume-hestia-projekt/svl/blob/main/CHANGELOG.md
Keywords: agent,agentic,linter,audit,spec-driven-development,ai-agents,architecture,governance,ddd,adr
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.7
Requires-Dist: psycopg[binary]>=3.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rfc8785==0.1.4
Requires-Dist: typer<0.26,>=0.12
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: anthropic>=0.40; extra == "dev"
Dynamic: license-file

# SvL — Sovereignty by Deliverable

[![CI](https://github.com/guillaume-hestia-projekt/svl/actions/workflows/ci.yml/badge.svg)](https://github.com/guillaume-hestia-projekt/svl/actions/workflows/ci.yml)
[![SvL self-audit](https://github.com/guillaume-hestia-projekt/svl/actions/workflows/svl-self-audit.yml/badge.svg)](https://github.com/guillaume-hestia-projekt/svl/actions/workflows/svl-self-audit.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Most agentic systems fail because authority boundaries are implicit.**

SvL audits **authority, ownership, and mutation boundaries** in agentic-system specs *before* runtime. It is a static gate — like ESLint or Spectral, but for AI agent specifications.

> A system becomes governable when every critical authority carries an **owner**, a **deliverable**, a **projection contract**, and an **audit trace**.

If any of those four is missing, `svl audit` raises a finding. That is the whole product.

Related note: [how SvL maps to governed AI sales agents](docs/agentic-sales-governance.md).

---

## 30-second demo

A spec where authority is implicit:

```yaml
# memory.yaml
agents:
  memory_writer:
    uses_llm: true
    mutates:
      - customer_memory
```

`svl audit memory.yaml --format beginner`:

```
memory.yaml — PASS  (3 warnings — exit 0 in default, exit 1 under --strict)
  0 blocking · 3 warning · 0 hint

! agents.memory_writer
  Component mutates state but produces no audit trace.
  fix: Add `audit_trace: <append-only log path>`.
  (SVL-AUDIT001)

! agents.memory_writer
  Authority-bearing component has no owner. Nobody is accountable.
  fix: Add `owner: <team-or-person>` naming the accountable party.
  (SVL-OWNER001)

! agents.memory_writer
  Authority-bearing component exposes no observable projection.
  fix: Add `projection_contract: <path>`.
  (SVL-PROJECTION001)
```

(The fourth invariant — *deliverable* — already passes here: in v2 doctrine, the `mutates: [customer_memory]` path *is* the deliverable. The rule fires only when no concrete artefact is named at all.)

The minimal fix — four primitives, declared explicitly:

```yaml
agents:
  customer_memory_writer:
    owner: customer_memory_team
    deliverable: customer_memory_record
    projection_contract: memory/read_model.yaml
    audit_trace: traces/customer_memory_mutations.jsonl
    mutates:
      - customer_memory
```

Now `svl audit --strict memory.yaml` passes.

---

## LLM usage does not define an agent

This is the single most useful idea in SvL:

> An agent is **not** defined by use of an LLM.
> An agent is **an entity that holds observable, auditable authority**.

That means:

- A **prompt** is not an agent.
- A **workflow** is not an agent.
- A **tool** is not an agent.
- A **skill** is not an agent.

…unless that prompt / workflow / tool / skill carries the four invariants. If it does, it is an agent — whatever its implementation. If it doesn't, it is a piece of plumbing.

SvL does not care whether your "agent" runs on Claude, on Mistral, on a Python function, or on a human typing into a terminal. SvL cares whether the system can be **audited**.

---

## What `svl audit` checks

For every authority declared in your spec, SvL looks for:

| Invariant | Question SvL asks |
|---|---|
| **Owner** | Who signed this off? Who is accountable when it goes wrong? |
| **Deliverable** | What concrete artefact does this produce? |
| **Projection Contract** | What can an external observer see, read, or call? |
| **Audit Trace** | What record proves the decision and survives a rollback? |

When any of the four is missing, `svl audit` raises a finding. Findings are written in operational language, not doctrinal language.

```
# Not this
Violation of Sovereignty Projection Doctrine.

# But this
This component mutates persistent state but exposes no observable
projection. The system cannot audit its decisions.
```

---

## What SvL is **not**

- **not** a runtime
- **not** an orchestrator
- **not** a multi-agent platform
- **not** an architectural cosmology
- **not** a framework

SvL reads a spec. It returns findings. It exits. That is all.

If you want a runtime, write one. If you want an orchestrator, pick one. SvL audits whatever you produce, before you ship it.

---

## Install

v1.x is on PyPI; **v2.0.0 is not yet published**. Pin to git while the v2 PR settles:

```bash
pip install "git+https://github.com/guillaume-hestia-projekt/svl.git@feat/v2-compression"
```

(Once v2 is tagged and released, `pip install svl-cli` will install v2 directly.)

```bash
svl --version
svl audit examples/v2/00_memory_writer_bad.yaml --format beginner
svl audit examples/v2/00_memory_writer_fixed.yaml --strict
svl autoplan "AI assistant that summarizes daily status notes" --project daily-status
```

The CLI has two commands. `audit` is the gate. `autoplan` is the recommender.
`autoplan` accepts either a path (file or directory) or a one-line idea
in quotes — useful for vibe-coder kickoff.

---

## Commands

### `svl audit <path>`

Static gate. Reads a YAML spec, a project directory, or an AGENTS.md file. Returns JSON by default, or a vibe-coder-friendly text format with `--format beginner`.

| Flag | Effect |
|---|---|
| `--format beginner` | Plain-text PASS/FAIL with one finding per block. |
| `--summary` | Counts only, skip findings list. |
| `--strict` | Treat warnings and observations as blocking. Use this in CI. |
| `--pack owasp-agentic-top10` | Add the OWASP Agentic Top 10 advisory rules. |
| `--explain SVL-OWNER001` | Print the metadata for a rule ID (e.g. `SVL-DELIVERABLE001`, `SVL-PROJECTION001`, `SVL-AUDIT001`). |
| `--type agentic` | Override contract-type inference. |

Exit code is `0` if no errors, `1` if any error finding is present. Wire it into CI before runtime.

### `svl autoplan <path> --project <name>`

Pattern recommender. Reads an intent description (YAML) or a project directory, returns architecture recommendations: agents to consider, memory strategies, runtime choices, ADR candidates, day-by-day build sequences.

Output is markdown by default, JSON with `--format json`. `--list-profiles` shows the available profiles.

The patterns surfaced here are **advisory** — they are *not* enforced by `svl audit`. They are observations from working systems: "this shape of project usually benefits from this kind of memory" / "this kind of orchestration tends to need a durable runtime".

---

## Use it in CI (GitHub Action)

SvL ships a reusable composite action. Gate your agent specs on every pull request — the same way you'd gate on lint or type-checks:

```yaml
# .github/workflows/svl.yml
name: SvL Audit
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: guillaume-hestia-projekt/svl@main
        with:
          paths: |
            specs/**/*.agentic.yaml
          pack: owasp-agentic-top10   # optional — OWASP Agentic Top 10 advisories
          strict: false               # set true to block on warnings too
```

| Input | Default | Effect |
|---|---|---|
| `paths` | _(required)_ | Glob(s) of spec files, space/newline-separated. `**` recursion supported. |
| `strict` | `false` | Treat warnings and observations as blocking, not just errors. |
| `pack` | `""` | Opt-in advisory pack. Supported: `owasp-agentic-top10`. |
| `ref` | `main` | Git ref of svl to install (svl is not yet on PyPI). |
| `install` | `git` | `git` installs svl at `ref`; `skip` uses a `svl` you installed yourself. |
| `python-version` | `3.12` | Python used to run svl. |

The action writes a findings table to the GitHub step summary and exits non-zero when the gate fails. A glob that matches **zero** files fails loudly rather than passing silently. This repo dogfoods the action on its own example specs — see [`.github/workflows/svl-self-audit.yml`](.github/workflows/svl-self-audit.yml).

---

## Patterns frequently observed

Earlier versions of SvL (v1.x) treated several patterns as *canonical doctrine*. They are now demoted to **patterns observed**, surfaced by `svl autoplan` when relevant, but no longer required to pass `svl audit`:

- **The 10 system functions** — memory kernel, runtime orchestrator, surface, policy engine, audit trail, etc. Useful as a checklist for large systems; not invariants.
- **The 3 system agents** — scope / system / sub-agent taxonomy. Useful as a vocabulary; not a constraint.
- **Living projection plane** — temporal contract between memory, runtime, and human gestures. Useful in real-time systems; folded into "projection contract" invariant.
- **Graph islands / memory blueprints / framework profiles** — patterns for medium-to-large systems. Surface via `svl autoplan` when the intent matches.

If you read older SvL material and a term puzzles you, look at [`doctrine/legacy/`](./doctrine/legacy/) — every v1 doctrine document is preserved verbatim there.

The current minimal doctrine is in [`doctrine/CORE.md`](./doctrine/CORE.md). It is two pages.

---

## Recherche & journal

Bancs d'essai sur la mémoire atomique gouvernée — corpus clients anonymisés, seules les métriques agrégées et la mécanique sont publiées. Chaque dossier a un `paper.md` (technique) et un `index.html` (essai).

- [**Retrievers without rerankers**](./research/2026-05-retriever-bench/) — sur un petit corpus atomique, `grep`/lexical bat le SQL exact. Le format de la question décide, pas le retriever.
- [**Notes on atomic memory growth at 558 claims**](./research/2026-05-atomic-governed-memory/) — observations sur l'écriture mémoire à l'échelle.
- [**Intent-Routed Retrieval doesn't beat the best solo retriever**](./research/2026-05-irr-design/) — l'ancre confiance-gated (claim-first/vecteur) + expansion 1-hop, sans routeur IRR.
- [**When the vector anchor loses**](./research/2026-05-vector-anchor-live-corpus/) — portage de la doctrine sur un corpus vivant : sur des atomes terses embeddés nus, le vecteur sous-performe le lexical ; l'expansion confirme son gain de rappel.

**[Construire un second cerveau](./story/)** — le journal build-in-public, en cinq chapitres : de Taskmind au noyau de mémoire gouvernée qui tourne en production. Version accessible : [`site/second-cerveau/`](./site/second-cerveau/).

---

## Status

- **Version:** 2.0.0 (post-compression). The pre-compression repo is tagged `v1-archive-final` on the same git history.
- **Tests:** 1070 passing, 18 skipped. CI runs lint + tests on Python 3.11 and 3.12.
- **License:** MIT.
- **PyPI:** [`svl-cli`](https://pypi.org/project/svl-cli/) (v1.x). v2.0.0 has not yet been published — pin to git for now.

---

## Project name

**SvL** — *Sovereignty by Deliverable*. Sovereignty is owning the deliverable that proves what you decided. SvL audits whether your spec actually says who owns what, and whether the audit can verify it.

There is no nicer way to say it. That's the whole framework.
