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.

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

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

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:

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

Or just run the Modeled check of the verifier itself:

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.