# verocase Tutorial

This is the tutorial for `verocase`.
`verocase` is a simple open source software (OSS) tool
that makes it *easy* and *efficient*
to create and maintain a small or moderately-sized assurance case,
e.g., for justifying why a system is secure against attack.
It's designed to be easy to use for humans *and* AI.

## What's an assurance case?

An assurance case is "a body of evidence organized into an argument demonstrating that some claim about a system holds (i.e., is assured). An assurance case is needed when it is important to show that a system exhibits some complex
property, such as safety, security, privacy, or reliability."
([NIST Special Publication 800-53A Revision 5](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-53Ar5.pdf)).

Assurance cases are in theory straightforward.
Typically you have a high-level claim that you repeatedly break down into
smaller claims that together demonstrate that the claim holds.
The problem is that as they get large, they can be painful to follow
or maintain if you just maintain a document.

`verocase` splits the work into two parts:

- A compact **LTAC file** (`case.ltac`) holds the argument structure:
  the claims, strategies, evidence, and how they relate.
- One or more **document files** (`case.md` etc.) hold the narrative detail
  and context: everything you'd want to say *about* each element.

`verocase` reads the LTAC file and regenerates the structured portions
of the document automatically (diagrams, headings, cross-reference links).
You write the free-form prose; `verocase` takes care of the boilerplate.

---

## Quick start

Create an empty directory and run `--start`:

```sh
mkdir demo && cd demo
verocase --start
```

This creates two files:

- `case.ltac`: a tiny starter argument (three elements)
- `case.md`: a Markdown document with placeholder regions

Open `case.ltac` in your editor. It looks something like this:

```ltac
- Claim Top: Top level claim
  - Claim G2: G2 is true {needssupport}
  - Claim G3: G3 is true {needssupport}
```

Open `case.md`. Near the top you'll see:

```markdown
<!-- verocase warning -->
<!-- WARNING: DO NOT EDIT text within verocase SELECTOR ... end verocase. -->
<!-- Those regions are regenerated. -->
<!-- end verocase -->
```

and further down:

```markdown
<!-- verocase package * -->
… generated diagram and index …
<!-- end verocase -->

<!-- verocase element Top -->
### Claim Top: Top level claim
…
<!-- end verocase -->

… more element regions …
```

Everything between a `<!-- verocase … -->` marker and `<!-- end verocase -->`
is managed by `verocase`: **don't edit inside those regions**.
Everything *outside* them is yours to write freely.

Now run `verocase` (no arguments) to regenerate:

```sh
verocase
```

It finds `case.ltac` and `case.md` automatically, validates the LTAC,
and rewrites `case.md` with fresh generated content.
The original `case.md` is backed up to `.backup/case.md` before any change.

---

## The LTAC file

### Element syntax

Every non-blank line in an LTAC file defines or cites one *element*:

```
INDENT - TYPE [^][IDENTIFIER]: statement text [{options}] [(ext_ref)]
```

- **`INDENT`**: two spaces per nesting level (root elements have none).
- **`-`**: the bullet marker.
- **`TYPE`**: the kind of element (see table below).
- **`^`**: if present, this is a *citation* of an element declared elsewhere.
- **`IDENTIFIER`**: a short name for the element, unique across the whole file.
  Identifiers may contain spaces and most printable characters (but not `:` or `^`).
  If omitted, the identifier is inferred from the statement text.
- **`: statement text`**: what this element asserts or describes.
- **`{options}`**: optional modifiers (see [Options](#options) below).
- **`(ext_ref)`**: optional URL or filename used as the click-target
  in diagrams.

One or more blank lines ends one *package* and begins the next.

### Element types

| Type | Purpose |
|---|---|
| `Claim` | A true-or-false statement asserted to hold |
| `Strategy` | An argument explaining how sub-claims or evidence collectively support a parent claim |
| `Evidence` | An artifact (document, test result, …) cited in support |
| `Context` | Background information or scope constraint for the parent element |
| `Assumption` | A claim accepted as true without further argument |
| `Justification` | A rationale or side-claim supporting a strategy |
| `Link` | A back-reference to an element already defined earlier in the same package |

The most common types are `Claim`, `Strategy`, and `Evidence`.
`Context` and `Assumption` add background or preconditions.

Here's a richer example:

```ltac
- Claim Secure: The system is adequately secure
  - Strategy SecStrategy: Argue by examining all attack vectors
    - Claim NetworkSafe: Network attacks are mitigated (network-analysis.pdf)
      - Evidence PenTest: Penetration test results (pentest-2024.pdf)
    - Claim AuthSafe: Authentication is robust
      - Evidence Authn: Authentication design review (authn-review.md)
    - Context Threat: Threat model is moderate adversary (threat-model.md)
```

### Options

Options appear in `{...}` near the end of a line and modify the element:

| Option | Meaning |
|---|---|
| `needssupport` | Placeholder; this claim still needs to be developed further |
| `assumed` | Accepted without proof; flags it visually in diagrams |
| `axiomatic` | Treated as a foundational axiom |
| `defeated` | No longer believed to hold |

The most useful option for active development is `needssupport`:
it flags leaves that aren't finished yet.
`--missing` adds `{needssupport}` automatically to any leaf claims.

### Identifiers

Identifiers must be unique across the entire LTAC file.
Use short, memorable names: `AuthnClaim`, `G2`, `PenTest`.
Spaces are legal: `- Claim Login Safe: Login is safe` works.
If you omit the identifier entirely the text becomes the identifier,
but explicit identifiers are easier to work with.

---

## The document file

### Marked regions

The document file is ordinary Markdown.
You can write whatever you like (headings, paragraphs, tables, images),
with one constraint: content between these two comment markers is owned
by `verocase`:

```markdown
<!-- verocase SELECTOR -->
…generated content (do not edit)…
<!-- end verocase -->
```

Each time you run `verocase`, it replaces everything between the markers
with freshly generated content for that `SELECTOR`.
Write your narrative *outside* these regions.

### Common selectors

| Region | What it generates |
|---|---|
| `<!-- verocase warning -->` | A "do not edit" reminder comment |
| `<!-- verocase package * -->` | Heading + diagram + index for every package |
| `<!-- verocase element ID -->` | Heading + cross-references for one element |
| `<!-- verocase sacm/mermaid ID -->` | SACM diagram for one package |
| `<!-- verocase gsn/mermaid * -->` | GSN diagrams for all packages |
| `<!-- verocase ltac/markdown * -->` | Full LTAC as a Markdown bullet list |
| `<!-- verocase statement ID -->` | Single-line statement text for ID |

See [reference.md](reference.md) for the full selector table.

### A typical document structure

```markdown
# My Assurance Case

<!-- verocase warning -->
<!-- end verocase -->

## Summary diagrams

<!-- verocase package * -->
<!-- end verocase -->

---

## Claim: The system is adequately secure {#claim-secure}

<!-- verocase element Secure -->
<!-- end verocase -->

Write your detailed narrative about this claim here.
Explain the threat model, scope, and any caveats.
This text is yours: verocase never touches it.

## Claim: Network attacks are mitigated

<!-- verocase element NetworkSafe -->
<!-- end verocase -->

More narrative here …
```

The `element` selector generates a stable heading and cross-reference
links (what supports this element, what it supports, where it's cited).
Your prose goes immediately after the `<!-- end verocase -->` line.

### Using `--missing` to scaffold element regions

If your LTAC has many elements, adding all the `element` regions by hand
is tedious. `--missing` does it for you:

```sh
verocase --missing
```

This re-renders all existing regions *and* appends a skeleton
`element` region for every LTAC element that has no region yet.
It also marks every leaf claim with `{needssupport}` if it lacks one.

After running `--missing`, open `case.md` and rearrange the appended
regions into the order you want. Move them next to the appropriate sections,
add your narrative after each `<!-- end verocase -->`, and run
`verocase` to regenerate.

---

## Running verocase

### Day-to-day workflow

The typical loop is:

1. Edit `case.ltac`: add/remove elements, change statements, restructure.
2. Edit `case.md`: add or revise narrative text *outside* the marked regions.
3. Run `verocase`: it validates the LTAC and regenerates all marked regions.
4. Review the updated document (diagrams, headings, cross-references).
4. In a few cases you may want to run special `verocase` commands, e.g.,
   `--move` will move an LTAC element from one place to another.
   You can also do this by directly editing the LTAC file, but it's
   sometimes easier to let the tool do it for you.
5. Repeat.

```sh
# Edit files, then:
verocase
```

`verocase` exits with code 0 on success and 1 if any error occurs.
Warnings (non-fatal issues) are printed to stderr but do not affect the exit
code unless you pass `--error`.

### Previewing without modifying files

Use `--stdout` to see what `verocase` would produce without changing anything:

```sh
verocase --stdout
```

This is useful for reviewing output or piping it into another tool.

For AI tools or any situation where you want to read the *document structure*
without wading through generated diagrams, use `--strip --stdout`:

```sh
verocase --strip --stdout
```

This produces the document with all selector regions emptied out (except
`warning`), making it much easier to read the outline and your prose.

### Validation only

To check the LTAC for errors without modifying any files:

```sh
verocase --validate
```

This is useful in CI pipelines: it exits non-zero if the LTAC is invalid
or if any declared element lacks an `element` selector in the documents.

---

## Multi-package cases

Once an assurance case grows large, a single flat list becomes hard to
navigate. Split it into *packages*: separate each top-level tree with a
blank line.

```ltac
- Claim Secure: The system is adequately secure
  - Claim ^NetworkSafe:
  - Claim ^AuthSafe:

- Claim NetworkSafe: Network attacks are mitigated
  - Evidence PenTest: Penetration test results (pentest-2024.pdf)

- Claim AuthSafe: Authentication is robust
  - Strategy AuthnStrategy: Argue by design and testing
    - Evidence AuthnDesign: Authentication design review
    - Evidence AuthnTest: Authentication test results
```

Each top-level `Claim` (with no indentation) begins a new package.
The `^` prefix on `^NetworkSafe` and `^AuthSafe` means those are
*citations*: references to elements defined in other packages.
Citations are how you connect packages together.

All packages must be reachable from the first element of the first package
by following children and citations. An isolated package is an error.

When you run `verocase package *`, each package gets its own section with
a diagram. Citations appear in the diagram as double-bracketed nodes
(SACM notation) or subroutine-box nodes (GSN notation), with links that
navigate to the package where the cited element is defined.

For more on packages and citations, see [reference.md](reference.md).

---

## Keeping things in sync

### Renaming an element

To rename an element everywhere (LTAC file and all document files):

```sh
verocase --rename OldId NewId
```

Identifiers with spaces need quoting:

```sh
verocase --rename "Login Safe" LoginSafe
```

### Updating a statement

To change an element's statement text everywhere, you can edit the
LTAC file and regenerate the document.

However, if you know the ID, you can use `--restate` like this:

```sh
verocase --restate AuthSafe "Authentication mechanisms are robust and tested"
```

You can also use `--update` (next).

### Syncing citation text

When you update a declaration's statement, any citations (`^ID: old text`)
become out of date. If you edit the declaration, you can
run `--update` to resync them:

```sh
verocase --update
```

This rewrites any citation whose text doesn't match its declaration.
Without `--update`, a mismatch produces a warning suggesting you run it.

---

## Tips

**Keep the LTAC focused on the argument.**
The LTAC file expresses the logical structure: claims, strategies, evidence.
Explanatory prose belongs in the document, outside the marked regions.

**Use meaningful identifiers.**
`AuthnClaim` is easier to work with than `G17`, especially for AI tools
that read the document. However, if you really prefer conventional
GSN naming conventions, you *can* use those conventions.

**Put `<!-- verocase warning -->` near the top.**
It reminds readers (and automated tools) that certain regions are generated.

**Use `--validate` in CI.**
A quick `verocase --validate` in your CI pipeline catches errors before
they reach reviewers.

**Use `--strip --stdout` to share the document with AI tools.**
Running `verocase --strip --stdout` produces a version of the document that
omits the bulky generated diagrams and boilerplate, leaving just the
document structure, your prose, and the LTAC markers.
This makes it much easier for an AI to understand and reason about your case.

---

## Where to go from here

- **[Reference manual](reference.md)**: complete documentation of all
  options, selectors, element types, configuration keys, diagram formats,
  validations, and file handling.
- **[Extended LTAC format](ltac-extended.txt)**: the formal specification
  of the LTAC file format.
- **[SACM notation in Mermaid](sacm-mermaid.md)**: how SACM concepts map
  to Mermaid shapes.
- **[GSN notation in Mermaid](gsn-in-mermaid.md)**: how GSN concepts map
  to Mermaid shapes.
- **[README](../README.md)**: project overview and installation.
