refactor: migrate Markdown to AsciiDoc

ARCHITECTURE.adoc

@@ -0,0 +1,129 @@
+== JanusKey Architecture — Reversibility Stack Junction Point
+
+=== Lineage
+
+....
+maa-framework (policy vision)
+  → absolute-zero (certified null operations — formal theory)
+    → januskey (development proof-of-concept — this repo)
+      → THREE downstream applications:
+         ├── ochrance    — neurosymbolic filesystem verification (Idris2)
+         ├── valence-shell — formally verified reversible shell (Rust + 6 proof systems)
+         └── aletheia    — reversible OS operations (early research)
+....
+
+JanusKey is the *junction point* where absolute-zero’s theoretical work
+on Certified Null Operations (CNOs) was first applied to practical file
+operations. The three downstream applications independently implemented
+reversibility, but shared no code — until the `+reversible-core+`
+extraction described below.
+
+=== Workspace Structure
+
+....
+januskey/
+├── crates/
+│   ├── reversible-core/    ← SHARED LIBRARY (the integration surface)
+│   │   ├── content_store   — SHA256 content-addressed storage
+│   │   ├── metadata        — OperationMetadata + MetadataStore (append-only log)
+│   │   ├── transaction     — Transaction lifecycle (begin/commit/rollback)
+│   │   ├── manifest        — A2ML emitter (bridge to ochrance verification)
+│   │   ├── error           — ReversibleError types
+│   │   └── lib             — ReversibleExecutor trait
+│   │
+│   └── januskey-cli/       ← CLI TOOL (depends on reversible-core)
+│       ├── operations      — FileOperation executor (actual filesystem ops)
+│       ├── keys            — Key management (AES-GCM, Argon2)
+│       ├── attestation     — Audit trail
+│       ├── obliteration    — Secure deletion
+│       ├── delta           — Differential operations
+│       ├── main            — jk CLI binary
+│       └── keys_cli        — jk-keys CLI binary
+....
+
+=== reversible-core: The Shared Foundation
+
+`+reversible-core+` is a lean Rust library crate (no CLI deps) that
+provides the types all three downstream applications share:
+
+==== ReversibleExecutor Trait
+
+[source,rust]
+----
+pub trait ReversibleExecutor {
+    type Op;
+    type Metadata;
+    type Error;
+
+    fn execute(&mut self, op: Self::Op) -> Result<Self::Metadata, Self::Error>;
+    fn undo(&mut self, metadata_id: &str) -> Result<Self::Metadata, Self::Error>;
+    fn generate_manifest(&self) -> Result<String, Self::Error>;
+}
+----
+
+This is the *Rust-side mirror* of ochrance’s `+VerifiedSubsystem+`
+interface (Idris2). The `+generate_manifest+` method emits A2ML that
+ochrance can parse and verify.
+
+==== CNO Correspondence
+
+Per absolute-zero, every `+OperationType+` has a known inverse:
+
+[cols=",,",options="header",]
+|===
+|Operation |Inverse |Property
+|Delete |Create |`+delete ; create ≡ CNO+`
+|Create |Delete |`+create ; delete ≡ CNO+`
+|Modify |Modify |Self-inverse (stores old+new content)
+|Move |Move |Self-inverse (swap src/dst)
+|Copy |Delete |`+copy ; delete_copy ≡ CNO+`
+|Chmod |Chmod |Self-inverse (stores old mode)
+|Chown |Chown |Self-inverse (stores old uid:gid)
+|===
+
+==== A2ML Bridge to Ochrance
+
+`+ManifestEmitter::generate()+` produces A2ML manifests containing: -
+Manifest header (version, subsystem, timestamp, Merkle root) - Refs (one
+per operation, with content hash) - Policy (verification mode)
+
+Ochrance parses these and produces `+VerificationProof+` witnesses: -
+`+LaxProof+` — manifest is well-formed - `+CheckedProof+` — all content
+hashes verified via BLAKE3 - `+AttestedProof+` — manifest is signed
+(Ed25519)
+
+=== Integration Status
+
+==== Phase 1: reversible-core extraction ✅ DONE (2026-03-21)
+
+Extracted core types from januskey into `+reversible-core+`. Workspace
+builds, 44 tests pass. januskey-cli re-exports all types for backward
+compatibility.
+
+==== Phase 2: valence-shell integration — NEXT
+
+Wire valence-shell (`+impl/rust-cli/+`) to depend on
+`+reversible-core+`: - Add `+ContentStore+` to `+ShellState+` for
+content-addressed undo data - Replace inline
+`+undo_data: Option<Vec<u8>>+` for large file content - Add
+`+a2ml_emitter.rs+` for manifest generation - Replace
+`+verification.rs+` stubs with `+ReversibleExecutor+` implementation
+
+==== Phase 3: ochrance ABI extension — PENDING
+
+Add reversibility types to ochrance’s Idris2 ABI: -
+`+src/abi/Ochrance/ABI/Reversibility.idr+` — `+ReversibleOp+`,
+`+ReversibilityProof+` -
+`+ochrance-core/Ochrance/Subsystem/OperationLog.idr+` —
+`+VerifiedSubsystem+` for op logs
+
+==== Phase 4: Cross-repo documentation — PENDING
+
+Update ARCHITECTURE.md and ECOSYSTEM.a2ml in all three repos with
+cross-references.
+
+==== Deferred
+
+* *aletheia*: Too early (Phase 0 research, no operation types yet)
+* *Merkle tree compatibility*: ochrance uses BLAKE3 height-indexed
+trees; Rust side needs compatible implementation

CHANGELOG.adoc

@@ -0,0 +1,84 @@
+== Changelog
+
+All notable changes to `+januskey+` will be documented in this file.
+
+This file is generated from conventional commits by the
+https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`]
+workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this
+repo’s CI to keep this file in sync automatically — see
+https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`]
+for the canonical config.
+
+The format follows https://keepachangelog.com/en/1.1.0/[Keep a
+Changelog]; this project aims to follow
+https://semver.org/spec/v2.0.0.html[Semantic Versioning].
+
+=== [Unreleased]
+
+==== Added
+
+* feat(crg): add crg-grade and crg-badge justfile recipes
+* feat(crg): add Current Grade badge anchor to READINESS.md
+* feat: add idrisiser Idris2 proof wrappers for JanusKey cryptographic
+core
+* feat: blitz — wire all tests, add property-based + regression, fix
+benchmarks, READINESS.md
+* feat: add E2E, P2P, aspect tests + criterion benchmarks
+* feat: add Zig FFI implementation + C header + integration tests
+* feat: complete Idris2 ABI — Foreign.idr + Proofs.idr
+* feat: add Idris2 ABI proofs — TypeLL Levels 1-12
+* feat: add stapeln.toml container definition
+* feat: deploy UX Manifesto infrastructure
+
+==== Fixed
+
+* fix(ci): bump a2ml/k9-validate-action pins to canonical (#33)
+* fix(ci): sync hypatia-scan.yml to canonical (#32)
+* fix(ci): adopt canonical hypatia-scan.yml (#31)
+* fix(ci): Phase-2 fleet submission must not fail the security gate
+(#30)
+* fix(ci): hypatia-scan workdir ($\{\{ env.HOME }} resolves empty) (#29)
+* fix(januskey): sweep .expect("`TODO: handle error`") — 166 sites
+cleared
+* fix: replace 60 unwrap() calls with expect() in security-critical
+modules
+* fix: quote $$ and use printf in setup.sh
+* fix: correct '`Provably Reversible`' claim — proofs are pending, not
+done
+* fix(scorecard): enforce granular permissions and add fuzzing
+placeholder
+
+==== Changed
+
+* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format)
+
+==== Documentation
+
+* docs(security): draft MCP-exposure threat model (AI-authored, pending
+human sign-off)
+* docs: add M2 estate audit report (2026-04-04)
+* docs: substantive CRG C annotation (EXPLAINME.adoc)
+* docs: add EXPLAINME.adoc — prove-it file backing README claims
+* docs: add ARCHITECTURE.md — reversibility stack junction point
+* docs: update SCM files with project information
+* docs: add CONTRIBUTING.md
+* docs: add checkpoint files for state tracking
+
+==== CI
+
+* ci(rust): convert rust-ci.yml to thin wrapper (standards#174) (#39)
+* ci: redistribute concurrency-cancel guard to read-only check workflows
+(#35)
+* ci: bump actions/upload-artifact SHA to current v4 (#27)
+* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate
+* ci: restore Dependabot security path + wire auto-merge
+
+=== Pre-history
+
+Prior commits to this file’s introduction are recorded in git history
+but not formally classified into Keep-a-Changelog sections. To backfill,
+run `+git cliff -o CHANGELOG.md+` locally using the canonical
+https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`]
+— this is one-shot mechanical work.
+
+'''''