feat: charter-scar — reference implementation of the scar invariant

.githooks/pre-push

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Pre-push gate for steward-charter.
+# PIPELINE PARITY: this hook mirrors .github/workflows/ci.yml (and `just check`).
+# When editing this file, update the pipeline + justfile to match.
+set -euo pipefail
+
+echo "pre-push: cargo fmt --check + clippy -D warnings + test"
+cargo fmt --check
+cargo clippy --all-targets -- -D warnings
+cargo test
+
+echo "pre-push: OK"

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+# CI for steward-charter.
+# HOOK PARITY: this pipeline is mirrored by .githooks/pre-push and `just check`.
+# When editing this file, update the push hook + justfile to match.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Toolchain
+        run: rustup component add rustfmt clippy
+      - name: Format
+        run: cargo fmt --check
+      - name: Lint
+        run: cargo clippy --all-targets -- -D warnings
+      - name: Test
+        run: cargo test

.gitignore

@@ -0,0 +1 @@
+/target

Cargo.toml

@@ -0,0 +1,27 @@
+# The Steward's Charter is both doctrine (STEWARDS_CHARTER.md) and the reference
+# implementations of the invariants that don't already live elsewhere in the
+# tree. `writ` lives in agent-mesh/agent-bridle and `provenance` in kyln; the
+# homeless primitives get canonical reference crates here. `charter-scar` is the
+# first.
+[workspace]
+resolver = "2"
+members = ["charter-scar"]
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.75"
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/Gilamonster-Foundation/steward-charter"
+authors = ["Shawn Hartsock <[email protected]>"]
+
+[workspace.dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+blake3 = "1"
+thiserror = "2"
+
+[profile.release]
+opt-level = 3
+lto = "thin"
+strip = true

README.md

@@ -31,6 +31,25 @@ The full doctrine — systems spec, the six audit questions, the gnostic gloss,
 where each primitive already lives in the tree — is in
 [`STEWARDS_CHARTER.md`](STEWARDS_CHARTER.md).
 
+## Reference implementations
+
+The Charter is doctrine **and** the canonical implementations of the invariants
+that don't already live elsewhere (`writ` lives in agent-mesh/agent-bridle,
+`provenance` in kyln). The homeless primitives get reference crates here.
+
+| Crate | Invariant | Status |
+|---|---|---|
+| [`charter-scar`](charter-scar) | `scar` | append-only, hash-chained record of metabolized failure (error + correction); refusals are recorded here too |
+
+```rust
+use charter_scar::{Scar, ScarKind, ScarLog};
+let mut log = ScarLog::new();
+let w = log.record(Scar::new(ScarKind::Mistake, "deploy on a Friday",
+                             "no rollback path", "two-hour outage"));
+log.heal(&w, "always land a rollback path first").unwrap(); // metabolized
+assert!(log.verify_chain());
+```
+
 ## How to cite it
 
 A repo adopts the Charter by pointing at it and naming which invariants it

charter-scar/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "charter-scar"
+description = "Reference implementation of the Steward's Charter `scar` invariant: an append-only, hash-chained record of metabolized failure (error + correction) — wisdom an agent can persist."
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+authors.workspace = true
+keywords = ["agent", "memory", "audit", "provenance", "steward-charter"]
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+blake3 = { workspace = true }
+thiserror = { workspace = true }