refactor: migrate Markdown to AsciiDoc

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -63,7 +63,7 @@ enforcement-workflow = ".github/workflows/estate-rules.yml"
 # .github/             CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, workflows/
 # .machine_readable/   AI manifests (0.1-AI-MANIFEST.a2ml), 6a2/ checkpoints,
 #                      contractiles/, configs/, anchors/, policies/, scripts/, svc/
-# build/               contractile.just, flake.nix, guix.scm, Containerfile,
+# build/               contractile.just, flake.guix, guix.scm, Containerfile,
 #                      just/*.just (Justfile section imports)
 # docs/                onboarding/, status/, architecture/, governance/  (all .adoc)
 # session/             dispatch.sh, custom-checks.k9, local-hooks.sh
@@ -103,7 +103,7 @@ enforcement-workflow = ".github/workflows/estate-rules.yml"
 #   build/just/groove.just     Groove protocol setup (after zig removed)
 #
 # Daily-use recipes (BUILD, TEST, LINT, RUN, DEPS, DOCS, CONTAINER, CI,
-# SECURITY, STATE, GUIX/NIX, MATRIX, VERSION CONTROL, UTILITIES, SESSION)
+# SECURITY, STATE, GUIX/GUIX, MATRIX, VERSION CONTROL, UTILITIES, SESSION)
 # stay in the root Justfile where users expect to find them.
 
 # === 5-PR cleanup pattern ===

ARCHITECTURE.adoc

@@ -0,0 +1,95 @@
+== Architecture
+
+=== Overview
+
+AcceleratorGate is the Julia admission and compatibility layer for the
+estate’s operation-first coprocessor runtime. It does not own numerical
+kernels and a backend type name is not a capability claim.
+
+Enaction owns runtime semantics, authoritative/advisory/remote-job
+policy, and the Idris2-defined native ABI. AcceleratorGate translates
+Julia requests into that operation vocabulary, admits providers using
+explicit evidence, and returns execution evidence to Julia consumers.
+
+=== Operation path
+
+[source,text]
+----
+Julia/domain value
+       |
+       v
+OperationRequest (version, layout, lane, evidence floors)
+       |
+       v
+deterministic provider planning
+       |
+       +-- pure-Zig Enaction native provider
+       +-- real hardware/provider adapter
+       +-- explicit reference provider
+       `-- explicit simulation (only when allow_simulation=true)
+       |
+       v
+result + ExecutionEvidence
+----
+
+Provider claims are per operation and include support, determinism,
+execution lanes, implementation kind, device class, and optional
+conformance digest. Simulations are refused by default. Authoritative
+claims must be `+canonical_exact+`. Remote providers may claim only
+`+remote_job+` execution. Once a provider has been planned, its runtime
+failure is returned to the caller; the registry never silently retries
+another provider.
+
+`+EnactionZigProvider+` loads the shared form of the same pure-Zig
+library used by the Rust adapter. It validates ABI version, layouts,
+capability records, status and execution evidence. There is no C
+implementation or Julia-owned copy of a kernel.
+
+The older device hierarchy and operation-specialty table remain as a
+legacy compatibility surface while consumers migrate. Environment flags
+and a type such as `+TPUBackend+` are discovery hints only and must not
+be presented as runnable hardware evidence.
+
+=== Directory Structure
+
+....
+.
+├── src/
+│   ├── AcceleratorGate.jl # legacy compatibility and module surface
+│   └── operations.jl      # central requests, evidence, planner, providers
+├── tests/        # Test suites
+├── docs/         # Documentation
+├── scripts/      # Utility scripts
+├── config/       # Configuration files
+├── LICENSE       # License file
+├── LICENSES/     # Full license texts
+└── README.adoc   # Project documentation
+....
+
+=== Design Principles
+
+* *Separation of Concerns*: Each module has a single responsibility
+* *Testability*: Code is written to be easily testable
+* *Documentation*: All public APIs are documented
+* *Configuration*: Environment-specific settings are externalized
+
+=== Dependencies
+
+* External dependencies are minimized and clearly declared
+* Version pinning is used for reproducibility
+
+=== Security Considerations
+
+* Sensitive data is never committed to the repository
+* Secrets are managed through environment variables or secure vaults
+* Regular dependency audits are performed
+
+=== Maintainability
+
+* Code follows consistent style guidelines
+* Pull requests require review and CI checks
+* Issues and discussions are tracked transparently
+
+'''''
+
+_Last updated: 2026-07-18_