2867c3437d5b34c6bd0b9f2a614d31fb7f5d6ace diff --git a/cli.md b/cli.md new file mode 100644 index 0000000000000000000000000000000000000000..e400caae167d77a48d3b75d338c3e2bbc68caf0d --- /dev/null +++ b/cli.md @@ -0,0 +1,513 @@ +Ja, hier is een concreet voorstel voor een sterkere Linux-native SAMA v2 verifier. +Doel van de Linux-first versie + +Een zo licht mogelijk, betrouwbaar en inspecteerbaar verificatiesysteem dat voornamelijk uit shell commands bestaat, met zo min mogelijk externe dependencies. +Voorgestelde structuur: `sama` CLI tool + +sama check # Alle checks draaien +sama check sorted +sama check law +sama check atomic +sama doctor # Systeem + project diagnose +sama graph # Toon import graph + +Implementatie per Conformance Check + +Hier is hoe elke check Linux-native kan worden geïmplementeerd: +Check Linux Commando’s / Tools Uitleg +1. Sorted find . -name "*.ts" -o -name "*.go" | sort + regex op prefix Check of alle bestanden een geldige prefix hebben en of de sortering klopt met laag-volgorde +2. Architecture `grep -E ’^(a0_ b1_ +3. Modeled (tests) find . -name "*.ts" ! -name "*.test.ts" | while read f; do test "$f.test.ts" ... Sibling testfile check +4. Modeled (boundary) `grep -E ’JSON.parse new URL +5. Atomic find . -name "*.ts" -exec wc -l {} + | awk '$1 > 700' Lijntelling + waarschuwing +6. The Law (Imports) grep -E 'from ["'\''].*\.\.' + tsort of eigen graph script Bouw een directed graph en check op cycles + richting +7. Consistency Combineer prefix extractie + import analyse Check of verklaarde laag overeenkomt met geïmporteerde lagen +Voorbeeld: Basis `sama check` script + +#!/usr/bin/env bash +# sama-check.sh + +PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd) +cd "$PROJECT_ROOT" + +echo "=== SAMA v2 Linux Verifier ===" + +fail=0 + +# Check 1: Sorted +echo -n "1. Sorted... " +if find src -name "*.ts" | grep -vE '^[a-d][0-3]_' > /dev/null; then + echo "FAIL (ongeldige prefix)" + fail=1 +else + echo "OK" +fi + +# Check 5: Atomic +echo -n "5. Atomic... " +if find src -name "*.ts" -exec wc -l {} + | awk '$1 > 700' | grep . > /dev/null; then + echo "FAIL (te grote files)" + fail=1 +else + echo "OK" +fi + +# Check 6: The Law (simpele versie) +echo -n "6. The Law... " +if grep -rE 'from ["'\''](\.\./)+[a-d][0-3]_' src | grep -E '^[a-d][0-1]_' > /dev/null; then + echo "FAIL (import omhoog)" + fail=1 +else + echo "OK" +fi + +if [ $fail -eq 0 ]; then + echo "✅ Alle checks geslaagd" +else + echo "❌ Er zijn fouten" + exit 1 +fi + +Aanbevolen tools (minimal dependencies) + + Core: bash, grep, find, awk, sed, wc, sort + + Performance: ripgrep (rg) als optie + + Graph analyse: graphviz (dot) + eigen parser of tsort + + Taal-specifiek: jq voor JSON-config, yq voor YAML + +Voordelen van deze aanpak + + Zeer lichtgewicht (draait op bijna elke Linux server/CI) + + Volledig inspecteerbaar (je kan elk commando los draaien) + + AI-agents kunnen dit veel makkelijker genereren en debuggen + + Sneller dan een zware TypeScript/Bun verifier + + Past perfect bij Unix-filosofie + +Wil je dat ik een volledig uitgewerkt script maak voor alle 7 checks? +Of wil je een versie voor een specifieke taal (bijv. TypeScript, Go, Python)? + +Bas van Cuilenburg + +Mon, May 25, 10:26 PM (7 hours ago) + + +to me + +✅ Hier is de nog verder uitgebreide versie met sama graph functionaliteit. +Volledige `sama` script (Linux-native + Graph support) + +#!/usr/bin/env bash +# ============================================= +# SAMA v2 Linux Verifier + Graph Tool +# Unix-native • Verbeterde versie +# ============================================= + +set -euo pipefail + +PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd) +cd "$PROJECT_ROOT" + +MAX_LINES=700 +SUPPORTED_EXTENSIONS="\.ts$|\.js$|\.go$|\.py$" + +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' + +fail=0 + +print_header() { + echo "=== SAMA v2 Linux Verifier ===" + echo "Project : $PROJECT_ROOT" + echo "Max lines : $MAX_LINES" + echo "=====================================" +} + +# ==================== CHECKS ==================== + +check_sorted() { + local bad=$(find src -type f -regextype posix-extended -regex ".*($SUPPORTED_EXTENSIONS)" | grep -vE '^[a-d][0-3]_' | head -10) + if [ -n "$bad" ]; then + echo -e "${RED}Bestanden zonder prefix:${NC}" + echo "$bad" + return 1 + fi + return 0 +} + +check_modeled_tests() { + local missing=() + while IFS= read -r file; do + local ext="${file##*.}" + local testfile="${file%.*}.test.${ext}" + [[ ! -f "$testfile" ]] && missing+=("$file") + done < <(find src -regextype posix-extended -regex ".*($SUPPORTED_EXTENSIONS)" | grep -E '^[b-c][0-3]_') + + if [ ${#missing[@]} -gt 0 ]; then + echo -e "${RED}Missende tests:${NC}" + printf ' %s\n' "${missing[@]}" + return 1 + fi + return 0 +} + +check_boundary() { + local bad=$(grep -rE 'JSON\.parse|new URL|URLSearchParams|qs\.parse' --include="*.ts" --include="*.js" src 2>/dev/null | grep -E '^[a-b][0-1]_' || true) + if [ -n "$bad" ]; then + echo -e "${RED}Boundary violations:${NC}" + echo "$bad" | head -8 + return 1 + fi + return 0 +} + +check_atomic() { + local big=$(find src -regextype posix-extended -regex ".*($SUPPORTED_EXTENSIONS)" -exec wc -l {} + 2>/dev/null | awk "\$1 > $MAX_LINES" || true) + if [ -n "$big" ]; then + echo -e "${RED}Te grote bestanden:${NC}" + echo "$big" + return 1 + fi + return 0 +} + +check_the_law() { + local bad=$(grep -rE 'from ["'\''](\.\./)+[a-d][0-3]_' src 2>/dev/null | grep -E '^[a-d][0-1]_' || true) + if [ -n "$bad" ]; then + echo -e "${RED}The Law overtredingen:${NC}" + echo "$bad" | head -6 + return 1 + fi + return 0 +} + +# ==================== GRAPH ==================== + +sama_graph() { + echo -e "${BLUE}Generating SAMA dependency graph...${NC}" + + local graph_file="/tmp/sama_graph.dot" + + cat > "$graph_file" << EOF +digraph SAMA { + rankdir=TB; + node [shape=box, fontname="monospace"]; + edge [arrowsize=0.6]; +EOF + + # Simpele import detectie + grep -rE 'from ["'\''](\./|\.\./)' src 2>/dev/null | head -50 | while read -r line; do + file=$(echo "$line" | cut -d: -f1) + import=$(echo "$line" | grep -oE 'from ["'\''][^"'\'']+') + if [[ -n "$file" && -n "$import" ]]; then + echo " \"$file\" -> \"$import\";" >> "$graph_file" + fi + done + + echo "}" >> "$graph_file" + + if command -v dot >/dev/null 2>&1; then + dot -Tpng "$graph_file" -o sama_graph.png + echo -e "${GREEN}✅ Graph gegenereerd: sama_graph.png${NC}" + else + echo -e "${YELLOW}Waarschuwing: Graphviz (dot) niet geïnstalleerd.${NC}" + echo "Installeer met: sudo apt install graphviz" + fi +} + +# ==================== MAIN ==================== + +print_header + +case "${1:-}" in + graph) + sama_graph + ;; + check) + case "${2:-}" in + sorted) check_sorted ;; + tests) check_modeled_tests ;; + boundary) check_boundary ;; + atomic) check_atomic ;; + law) check_the_law ;; + *) + echo "Beschikbare checks: sorted, tests, boundary, atomic, law" + ;; + esac + ;; + *) + # Alle checks draaien + echo "Running all checks..." + check_sorted && echo -e "${GREEN}1. Sorted ...................... PASS${NC}" || { echo -e "${RED}1. Sorted ...................... FAIL${NC}"; fail=1; } + check_modeled_tests && echo -e "${GREEN}3. Modeled (tests) ............. PASS${NC}" || { echo -e "${RED}3. Modeled (tests) ............. FAIL${NC}"; fail=1; } + check_boundary && echo -e "${GREEN}4. Modeled (boundary) .......... PASS${NC}" || { echo -e "${RED}4. Modeled (boundary) .......... FAIL${NC}"; fail=1; } + check_atomic && echo -e "${GREEN}5. Atomic ...................... PASS${NC}" || { echo -e "${RED}5. Atomic ...................... FAIL${NC}"; fail=1; } + check_the_law && echo -e "${GREEN}6. The Law ..................... PASS${NC}" || { echo -e "${RED}6. The Law ..................... FAIL${NC}"; fail=1; } + ;; +esac + +echo "=====================================" +if [ $fail -eq 0 ]; then + echo -e "${GREEN}✅ SAMA v2 Compliant${NC}" +else + echo -e "${RED}❌ SAMA v2 issues found${NC}" + exit 1 +fi + +Gebruik: + +sama # Alle checks +sama check law # Alleen The Law +sama graph # Genereert dependency graph (sama_graph.png) + +Wil je nog verder gaan? Bijvoorbeeld: + + Ondersteuning voor Go of Python verbeteren? + + Een sama doctor commando toevoegen? + + Het script nog simpeler/moderner maken met fd + rg? + +Laat het weten! + + +Met vriendelijke groet / Mit freundlichen Grüßen / Kind regards, ______________________________ + +Bas van Cuilenburg + + +Bas van Cuilenburg + +Mon, May 25, 10:30 PM (7 hours ago) + + +to me + +✅ Hier is de volledige, 100% SAMA v2 compliant versie van de Linux Verifier. +Projectstructuur (SAMA v2 compliant) + +sama-cli/ +├── sama # Hoofd executable (wrapper) +├── src/ +│ ├── a0_main.sh # Layer 3 - Entry +│ ├── b1_checks.sh # Layer 1 - Core +│ ├── b2_graph.sh # Layer 2 - Adapter +│ ├── c1_utils.sh # Layer 1 - Core +│ └── c2_constants.sh # Layer 0 - Pure +└── tests/ + ├── b1_checks.test.sh + └── c1_utils.test.sh + +1. `src/c2_constants.sh` (Layer 0 - Pure) + +#!/usr/bin/env bash +# c2_constants.sh + +MAX_LINES=700 +SUPPORTED_EXTENSIONS="\.ts$|\.js$|\.go$|\.py$|\.sh$" + +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' + +2. `src/c1_utils.sh` (Layer 1 - Core) + +#!/usr/bin/env bash +# c1_utils.sh + +print_header() { + echo "=== SAMA v2 Linux Verifier ===" + echo "Project : $(pwd)" + echo "Max lines : $MAX_LINES" + echo "=====================================" +} + +run_check() { + local name="$1" + local func="$2" + echo -n "$name " + printf "%-28s" "........................" + if $func; then + echo -e "${GREEN}PASS${NC}" + return 0 + else + echo -e "${RED}FAIL${NC}" + return 1 + fi +} + +3. `src/b1_checks.sh` (Layer 1 - Core) + +#!/usr/bin/env bash +# b1_checks.sh + +source "src/c2_constants.sh" + +check_sorted() { + local bad=$(find src -type f -regextype posix-extended -regex ".*($SUPPORTED_EXTENSIONS)" | grep -vE '^[a-d][0-3]_' | head -10) + if [ -n "$bad" ]; then + echo -e "${RED}Bestanden zonder geldige prefix:${NC}" + echo "$bad" + return 1 + fi + return 0 +} + +check_modeled_tests() { + local missing=() + while IFS= read -r file; do + local ext="${file##*.}" + local testfile="${file%.*}.test.${ext}" + [[ ! -f "$testfile" ]] && missing+=("$file") + done < <(find src -regextype posix-extended -regex ".*($SUPPORTED_EXTENSIONS)" | grep -E '^[b-c][0-3]_') + + if [ ${#missing[@]} -gt 0 ]; then + echo -e "${RED}Missende testbestanden:${NC}" + printf ' %s\n' "${missing[@]}" + return 1 + fi + return 0 +} + +check_boundary() { + local bad=$(grep -rE 'JSON\.parse|new URL|URLSearchParams|qs\.parse' --include="*.ts" --include="*.js" src 2>/dev/null | grep -E '^[a-b][0-1]_' || true) + if [ -n "$bad" ]; then + echo -e "${RED}Boundary violations (parsing buiten Layer 2):${NC}" + echo "$bad" | head -8 + return 1 + fi + return 0 +} + +check_atomic() { + local big=$(find src -regextype posix-extended -regex ".*($SUPPORTED_EXTENSIONS)" -exec wc -l {} + 2>/dev/null | awk "\$1 > $MAX_LINES" || true) + if [ -n "$big" ]; then + echo -e "${RED}Bestanden groter dan ${MAX_LINES} regels:${NC}" + echo "$big" + return 1 + fi + return 0 +} + +check_the_law() { + local bad=$(grep -rE 'from ["'\''](\.\./)+[a-d][0-3]_' src 2>/dev/null | grep -E '^[a-d][0-1]_' || true) + if [ -n "$bad" ]; then + echo -e "${RED}The Law overtredingen (import omhoog):${NC}" + echo "$bad" | head -6 + return 1 + fi + return 0 +} + +4. `src/b2_graph.sh` (Layer 2 - Adapter) + +#!/usr/bin/env bash +# b2_graph.sh + +sama_graph() { + echo -e "${BLUE}Generating SAMA dependency graph...${NC}" + + local graph_file="/tmp/sama_graph.dot" + + cat > "$graph_file" << EOF +digraph SAMA { + rankdir=TB; + node [shape=box, fontname="monospace"]; + edge [arrowsize=0.6]; +EOF + + grep -rE 'source |from ["'\'']' src 2>/dev/null | head -40 | while read -r line; do + file=$(echo "$line" | cut -d: -f1) + import=$(echo "$line" | grep -oE '(source |from ["'\''])[^"'\'' ]+' | sed 's/.* //') + if [[ -n "$file" && -n "$import" ]]; then + echo " \"$file\" -> \"$import\";" >> "$graph_file" + fi + done + + echo "}" >> "$graph_file" + + if command -v dot >/dev/null 2>&1; then + dot -Tpng "$graph_file" -o sama_graph.png + echo -e "${GREEN}✅ Graph gegenereerd → sama_graph.png${NC}" + else + echo -e "${YELLOW}Graphviz niet gevonden. Installeer met: sudo apt install graphviz${NC}" + fi +} + +5. `src/a0_main.sh` (Layer 3 - Entry) + +#!/usr/bin/env bash +# a0_main.sh + +source "src/c2_constants.sh" +source "src/c1_utils.sh" +source "src/b1_checks.sh" +source "src/b2_graph.sh" + +fail=0 + +print_header + +case "${1:-}" in + graph) + sama_graph + ;; + check) + case "${2:-}" in + sorted) check_sorted ;; + tests) check_modeled_tests ;; + boundary) check_boundary ;; + atomic) check_atomic ;; + law) check_the_law ;; + *) echo "Beschikbare checks: sorted, tests, boundary, atomic, law" ;; + esac + ;; + *) + run_check "1. Sorted" check_sorted || fail=1 + run_check "3. Modeled (tests)" check_modeled_tests || fail=1 + run_check "4. Modeled (boundary)" check_boundary || fail=1 + run_check "5. Atomic" check_atomic || fail=1 + run_check "6. The Law" check_the_law || fail=1 + ;; +esac + +echo "=====================================" +if [ $fail -eq 0 ]; then + echo -e "${GREEN}✅ SAMA v2 Compliant — Alles in orde!${NC}" +else + echo -e "${RED}❌ SAMA v2 — Er zijn overtredingen${NC}" + exit 1 +fi + +6. Hoofd executable: `sama` (in root) + +#!/usr/bin/env bash +# sama + +cd "$(dirname "$0")" +exec bash src/a0_main.sh "$@" + +Installatie commando’s + +# Maak alle files executable +chmod +x sama src/*.sh + +# Test het +./sama +./sama graph + +Wil je dat ik ook de testbestanden (*.test.sh) toevoeg, of een sama doctor commando? + + +Met vriendelijke groet / Mit freundlichen Grüßen / Kind regards, ______________________________ diff --git a/goals/sama-cli-shell-verifier.md b/goals/sama-cli-shell-verifier.md new file mode 100644 index 0000000000000000000000000000000000000000..711343e66535517b016f1fbd4c61d2b23eaaa833 --- /dev/null +++ b/goals/sama-cli-shell-verifier.md @@ -0,0 +1,84 @@ +--- +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: null +merge_sha: null +status: pending +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*_.{ts,sh}` and `c*_.{ts,sh}` source file has a sibling `.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 "../"` 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. diff --git a/src/a31_goals.ts b/src/a31_goals.ts index a0405f0db6adde579ac9c0bde1585b7074fed18e..29fe20dcd8e2db161934eb15510f59f0721cb7d7 100644 --- a/src/a31_goals.ts +++ b/src/a31_goals.ts @@ -38,6 +38,19 @@ export interface GoalEntry { } export const ALL_GOALS: GoalEntry[] = [ + { + 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", + prNumber: null, + mergeSha: null, + status: "pending", + relatedPosts: [ + "sama-v2-verifier-and-the-rename", + "sama-v2-metrics-emitter", + ], + }, { slug: "blog-date-prefix", title: "Move /blog/ → /blog// — data-driven portability test",