# sama-cli — the SAMA v2 shell verifier

A second, independent implementation of the SAMA v2 §4 conformance
checks, written in **pure POSIX shell** (bash + find + grep + awk +
wc + sed + sort). Acts as the cross-verifier oracle for the
TypeScript verifier at [`src/b32_sama_v2_verify.ts`](../../src/b32_sama_v2_verify.ts).

When both verifiers report `7 / 7 ✓` against the same source tree,
the verdict is empirical — two implementations of the same spec, in
different languages on different runtimes, agree.

## Usage

```sh
sama check                         # verify the current repo
sama check --src=path --profile=path/sama.profile.toml
sama check --summary               # one-line verdict, for scripting
sama check sorted                  # run a single check
sama graph [out.dot]               # emit graphviz .dot of imports
sama doctor                        # show tool availability
sama --version
sama --help
```

## Architecture (SAMA v2 self-conforming)

```
tools/sama-cli/
├── sama                           # entry wrapper
├── sama.profile.toml              # SAMA v2 profile for THIS sub-project
├── cross-verify.sh                # run both verifiers, assert agreement
├── run-ts-verifier.ts             # thin Bun CLI bridge to the TS verifier
├── README.md                      # this file
└── src/
    ├── a31_constants.sh           # Layer 0 — Pure (constants only)
    ├── b32_utils.sh               # Layer 1 — Core (helpers)
    ├── b32_utils.test.sh          # Sibling test (per §4.3 Modeled)
    ├── b32_checks.sh              # Layer 1 — Core (the 7 §4 checks)
    ├── b32_checks.test.sh         # Sibling test
    ├── c14_graph.sh               # Layer 2 — Adapter (calls graphviz dot)
    ├── c14_graph.test.sh          # Sibling test
    └── d21_main.sh                # Layer 3 — Entry (dispatcher)
```

**Layer mapping** (canonical, matches the rest of the repo):
- `a*_` = Layer 0 Pure (no I/O, no side effects)
- `b*_` = Layer 1 Core (pure-function logic + render)
- `c*_` = Layer 2 Adapter (the boundary — calls external tools)
- `d*_` = Layer 3 Entry (dispatcher, argv, exit)

The `cli.md` email proposal at the repo root inverted this mapping
(`a*_` → Layer 3, `c*_` → Layer 0) — the actual implementation
explicitly corrects that bug per the `/goals/sama-cli-shell-verifier`
contract. See [/sama/v2 §1.1](https://tdd.md/sama/v2) for the
canonical layer table.

## Cross-verifier agreement

The empirical claim:

> *"Two independent implementations of the SAMA v2 §4 spec, written
> in different languages on different runtimes, will produce
> identical verdicts against any spec-conforming codebase. If they
> disagree on this repo's 7/7 ✓, one is wrong — and per /sama/v2 §0
> the disagreement is auditable from the spec prose alone."*

Run it:

```sh
tools/sama-cli/cross-verify.sh           # against this repo
tools/sama-cli/cross-verify.sh --self    # against tools/sama-cli/src
```

Exit `0` if the verdicts match, `1` if they diverge. A divergence
is a §6 evolution-policy pressure point — the place where the spec
prose admits multiple readings.

## Sibling tests

Each `b*_` and `c*_` source file has a `<name>.test.sh` sibling
(per §4.3 Modeled). The test harness is in-file — a minimal
`assert_eq` / `assert_contains` pair, no `bats` dependency. Run all
tests:

```sh
for t in tools/sama-cli/src/*.test.sh; do bash "$t"; done
```

Or just run the `Modeled` check of the verifier itself:

```sh
tools/sama-cli/sama check modeled-tests \
  --src=tools/sama-cli/src \
  --profile=tools/sama-cli/sama.profile.toml
```

## Anti-fudge constraints (per the /goal)

- **No Bun, no Node, no language runtime beyond POSIX shell.** Pure
  bash + standard Linux utilities. `dot` (graphviz) is optional and
  only used by `sama graph`.
- **Layer mapping is canonical** (`a*_` = Pure, `d*_` = Entry — not
  the cli.md email inversion).
- **Self-conformance is non-negotiable.** `sama check` against this
  directory's own `src/` returns `7 / 7 ✓`.
- **`sama-import:` comment annotation.** Shell sourcing is too
  heterogeneous to parse robustly (paths via `${VAR}`, `$BASH_SOURCE`,
  etc.) — so each source file declares its imports with explicit
  `# sama-import: <filename.sh>` comments near the top. The
  verifier reads these as ground truth for the §1.2 Law check.
- **Two-verifier agreement is load-bearing.** A disagreement between
  TS and shell verifiers is a spec ambiguity, not a "one of them is
  wrong" — but the burden of proof lies with the shell verifier
  until the §5 cross-repo evidence accumulates.