syntaxai/tdd.md · main · goals / sama-cli-shell-verifier.md

sama-cli-shell-verifier.md 85 lines · 9816 bytes raw · source

slug: sama-cli-shell-verifier title: Linux-native shell-based SAMA v2 verifier — second independent implementation date: 2026-05-25 branch: sama-cli-shell-verifier pr_number: 60 merge_sha: 13f9114 status: shipped related_posts: [sama-v2-verifier-and-the-rename, sama-v2-metrics-emitter]

Goal: Build a second, independent SAMA v2 §4 verifier implemented as Linux-native shell scripts (bash + find + grep + awk + wc + sed — no Bun, no Node, no language runtime beyond POSIX). Lives at tools/sama-cli/ inside this repo. Acts as the cross-verifier reference per /sama/v2 §6 evolution policy: two independent implementations of the spec produce the same verdict against the same codebase. The load-bearing claim that follows is "the spec is reproducible from prose alone — two teams could implement it, and both implementations agree." The cli.md email at the repo root sketches the design; this /goal corrects its broken prefix mapping and binds the implementation to actually pass the existing /sama/v2/verify.

Why this matters empirically. Today, /sama/v2/verify is one program, written in TypeScript, run on Bun. If that program is wrong, the site's claim "this codebase scores 7/7 ✓" is unaudited — there's no independent oracle. A second implementation in a fundamentally different language (shell, not TS) running on different primitives (POSIX find/grep, not Bun's filesystem APIs) creates the oracle. If both agree on 7/7 ✓ across every commit, the verdict is empirical, not just compiled.

The cli.md proposal at the repo root has a critical layer-mapping bug — it maps a*_ to Layer 3, c*_ to Layer 1, etc., which is backwards from this codebase's canonical mapping (a=Pure, b=Core, c=Adapter, d=Entry). Under the cli.md mapping the proposal's own files would FAIL §4.1 Sorted. This /goal explicitly corrects that and uses the canonical SAMA v2 prefix scheme throughout.

Done when:

  • tools/sama-cli/ directory exists with this exact structure (canonical layer mapping applied):
    tools/sama-cli/
├── sama                    # entry wrapper, calls src/d*_main.sh
├── sama.profile.toml       # SAMA v2 profile for THIS sub-project
└── src/
    ├── a31_constants.sh    # Layer 0 — Pure: MAX_LINES, color codes, supported exts
    ├── b32_checks.sh       # Layer 1 — Core: the 7 §4 checks as pure functions
    ├── b32_checks.test.sh  # Sibling test for b32_checks.sh
    ├── b32_utils.sh        # Layer 1 — Core: print_header, run_check, status helpers
    ├── b32_utils.test.sh   # Sibling test for b32_utils.sh
    ├── c14_graph.sh        # Layer 2 — Adapter: calls graphviz dot (filesystem write)
    ├── c14_graph.test.sh   # Sibling test for c14_graph.sh
    └── d21_main.sh         # Layer 3 — Entry: dispatcher for `sama check`, `sama graph`, etc.
  • tools/sama-cli/sama --help prints usage covering: sama check [check-name], sama graph, sama doctor (diagnostic: which tools are installed).
  • Each of the 7 §4 checks implemented:
    • check_sorted — verify every file in src/ matches ^[a-d][0-9]_ and the lex-order matches layer order
    • check_architecture — verify imports respect the prefix-to-layer contract (a=Pure imports nothing local; d=Entry can import any lower; b/c follow the Law)
    • check_modeled_tests — every b*_<name>.{ts,sh} and c*_<name>.{ts,sh} source file has a sibling <name>.test.{ts,sh}
    • check_modeled_boundary — JSON.parse|new URL|URLSearchParams|qs.parse only appears in c*_ files
    • check_atomic — no source file exceeds 700 LOC (configurable via sama.profile.toml)
    • check_the_law — no import from "../<higher-prefix>" violations; graph is acyclic
    • check_consistency — declared layer (file prefix) matches actual imported layers (no a31_ importing from b32_)
  • Cross-verifier agreement test: tools/sama-cli/sama check run against THIS repo's src/ produces 7/7 ✓ — same verdict as bun src/b32_sama_v2_verify.ts (the existing TS verifier). A small bash script tools/sama-cli/cross-verify.sh runs both and asserts the verdicts are identical (exit 0 if they agree, exit 1 if they don't).
  • Self-conformance: tools/sama-cli/sama check pointed at its OWN tools/sama-cli/src/ returns 7/7 ✓. The shell verifier verifies itself under the same rules.
  • tools/sama-cli/sama graph generates a .dot file and (if graphviz dot is installed) renders a PNG showing the import/source-relationship graph for the target src/ tree.
  • tools/sama-cli/sama doctor lists every tool the verifier uses (bash, find, grep, awk, wc, sed, sort, optionally dot) and reports which are present + which version.
  • A new blog post planned (NOT in this /goal — a follow-up plan-post) describes the two-verifier-agreement empirical claim. This /goal just builds the second implementation; the empirical-chain blog post is the next iteration.
  • All existing bun test runs still pass (no regression — this /goal adds files in tools/sama-cli/ and doesn't modify any existing src/).
  • /sama/v2/verify (the TS verifier exposed on the live site) still reports 7/7 ✓.
  • Optional but recommended: a CI hook (or a simple make verify Makefile target) that runs BOTH verifiers and fails if they disagree. Forces ongoing agreement, not just one-time agreement.
  • Deployed; live-verify with curl:
    • /sama/v2/verify → 7/7 ✓ (the TS verifier, unchanged)
    • /GIT/tdd.md/blob/main/tools/sama-cli/sama → 200 (the shell entry is browseable on-site)
    • /GIT/tdd.md/tree/main/tools/sama-cli → 200 (the directory listing is reachable)
    • /goals/sama-cli-shell-verifier → 200 with status: shipped (this very goal file flipped post-merge)

Constraints (anti-fudge):

  • Layer mapping is a*_ = Layer 0 Pure, b*_ = Layer 1 Core, c*_ = Layer 2 Adapter, d*_ = Layer 3 Entry. This matches the canonical spec at /sama/v2 §1.1 and this repo's existing src/. The cli.md proposal's mapping is wrong; do not copy it.
  • Two-verifier agreement is load-bearing. If the shell verifier produces a different verdict than the TS verifier on this codebase, the shell verifier is wrong by default. Only after both have been stress-tested against external repos (the §5 cross-repo measurements) can a disagreement be resolved by spec-reading rather than by deferring to one.
  • No Bun, no Node, no language runtime. Pure POSIX shell + standard Linux utilities. awk, sed, find, grep, wc, sort, bash. dot (graphviz) is optional and only for the graph command.
  • Self-conformance is non-negotiable. The verifier must score 7/7 ✓ against its own source tree. If it doesn't, the design is broken before it ships.
  • Sibling tests for every b_ and c_ file.** Per /sama/v2 §4.3. Use a minimal test runner — a bash function that asserts expected exit codes / output, or bats if it's available. Document the choice in tools/sama-cli/README.md.
  • tools/sama-cli/ is a sub-project, not a sub-directory. It has its own sama.profile.toml. The existing repo's profile is unchanged. The two profiles let the existing TS verifier ignore tools/sama-cli/ files (since they're outside src/) and vice versa.
  • No symlinks. No git submodules. No external repo dependency. Everything lands in this repo, in tools/sama-cli/. The /GIT/ browser surfaces it automatically.
  • Containerfile: add COPY tools ./tools if shell verifier should run from the deployed container; otherwise the directory stays repo-only and isn't shipped to production. Decide based on whether sama doctor or sama graph should be runnable on the live server. Default: ship it (per the PR #46 lessons-learned that new top-level dirs need explicit COPY).
  • Site language English-only in all shell comments + output strings.
  • GitHub flow via flatpak-spawn (branch → PR → merge → push p620 → deploy via flatpak-spawn --host scripts/p620/deploy-tdd-md.sh).
  • Do NOT change /sama/v2/verify or src/b32_sama_v2_verify.ts. The TS verifier is canonical for now.
  • PR body MUST embed this verbatim /goal under ## /goal per feedback_goal_authoring_workflow.md.

Load-bearing files to read FIRST:

  • cli.md at the repo root (the email proposal — read it, then ignore its prefix mapping; use the section structure but rebind the layer prefixes correctly)
  • src/b32_sama_v2_verify.ts (the canonical TS verifier — the shell version must produce the same 7/7 ✓ on this repo)
  • src/a31_sama_v2.ts (the spec constants: MAX_LINES = 700, WORKING_SET_MIN_LOC = 50, WORKING_SET_MAX_LOC = 500, layer prefix scheme — replicate as constants in tools/sama-cli/src/a31_constants.sh)
  • sama.profile.toml at the repo root (the profile shape — tools/sama-cli/sama.profile.toml should mirror it for its own src/)
  • /sama/v2 (the canonical spec — §4 checks, §1.2 the Law)
  • /blog/2026-05/sama-v2-verifier-and-the-rename (the original verifier-and-renaming story — context for why the shell version exists)
  • /blog/2026-05/sama-v2-metrics-emitter (the §5 emitter — same shape of building a second pure helper that agrees with an existing one structurally)

Falsifiable claim this /goal lays cable for (the next iteration tests it):

"Two independent implementations of the SAMA v2 §4 spec, written in different languages on different runtimes, will produce identical verdicts against any given codebase that conforms to the spec. If they disagree on this repo at 7/7 ✓, one of them is wrong — and per /sama/v2 §0 the disagreement is auditable from the spec prose alone."

The next blog post after this /goal merges will document: which checks the two verifiers agreed on byte-for-byte vs. which required the SAMA v2 spec to disambiguate. That's the §6 evolution-policy mechanism in action — disagreements between independent implementations are the spec's empirical-validation pressure-points.