svl-cli 2.0.0

Sovereignty by Deliverable — a static gate for agentic-system specifications. Checks owner, deliverable, projection contract, audit trace.

SvL — Sovereignty by Deliverable

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.

---

30-second demo

A spec where authority is implicit:

# 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:

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:

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.)

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:

# .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.

---

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/ — every v1 doctrine document is preserved verbatim there.

The current minimal doctrine is in 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 — 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 — observations sur l'écriture mémoire à l'échelle.
• Intent-Routed Retrieval doesn't beat the best solo retriever — l'ancre confiance-gated (claim-first/vecteur) + expansion 1-hop, sans routeur IRR.
• When the vector anchor loses — 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 — 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/.

---

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 (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.