refactor: migrate Markdown to AsciiDoc

.claude/PROJECT.adoc

@@ -0,0 +1,34 @@
+== My Lang - Claude Code Instructions
+
+This repository contains the My Lang programming language
+implementation.
+
+=== Project Structure
+
+....
+my-lang/
+├── .claude/         # AI assistant instructions
+├── .git/           # Version control
+├── .gitignore      # Git ignore rules
+├── .editorconfig   # Editor configuration
+└── ...             # Language files
+....
+
+=== Build Commands
+
+Refer to project-specific documentation.
+
+=== Coding Conventions
+
+* Follow hyperpolymath standards
+* All code must have SPDX license headers
+* Use approved languages only (see CLAUDE.md)
+* Document all non-obvious decisions
+
+=== Security
+
+* No hardcoded secrets
+* All secrets through environment variables or secret management
+* SHA-pinned dependencies where applicable
+* HTTPS only, no HTTP URLs
+* No MD5/SHA1 for security purposes

ARCHITECTURE.adoc

@@ -0,0 +1,97 @@
+== Architecture
+
+=== Overview
+
+my-lang is a Rust-implemented language with a mechanised proof core. The
+repository is a Cargo workspace plus proof, dialect, and conformance
+trees. This file describes the layout as it actually is; for the
+authoritative state of the proofs, see `+proofs/STATUS.md+` (that
+registry wins over any other prose, including this file).
+
+=== The dialect containment hierarchy
+
+The three real dialects are *nested subsets, not parallel languages*:
+
+....
+Solo  ⊂  Duet  ⊂  Ensemble
+....
+
+* *Solo* — the innermost kernel.
+* *Duet* — everything in Solo plus more; mechanised as "`ensemble
+restricted to 2-party by projection`" (S2 track).
+* *Ensemble* — the full language (session-typed π-calculus core, S1
+track).
+* *Me* — not a fourth layer: an on-the-fly projector that cuts the
+hierarchy at a chosen point. Its Rust scaffolding is sidelined in
+`+_exploratory/me-scaffolding/+` (see `+SIDELINED.adoc+` there) and is
+*not* part of the active workspace.
+
+Audits must grade the layered stack, not three separate compilers: a
+broken Solo breaks Duet and Ensemble by transitivity.
+
+=== Directory structure
+
+....
+.
+├── crates/            # Cargo workspace (15 members)
+│   ├── my-lang/       #   core: lexer/parser/checker (largest crate)
+│   ├── my-cli/        #   `my` binary
+│   ├── my-parser/     #   parser scaffolding
+│   ├── my-hir/        #   high-level IR
+│   ├── my-mir/        #   mid-level IR
+│   ├── my-qtt/        #   QTT verified-core checker (faithful port of
+│   │                  #   the Coq R5 `check` / R5b `aff_type_dec`)
+│   ├── my-llvm/       #   LLVM codegen (needs system LLVM 21; excluded
+│   │                  #   from coverage CI for hermeticity)
+│   ├── my-lsp/        #   language server
+│   ├── my-dap/        #   debug adapter
+│   ├── my-debug/      #   debugging support
+│   ├── my-fmt/        #   formatter
+│   ├── my-lint/       #   linter
+│   ├── my-test/       #   test harness
+│   ├── my-pkg/        #   package manager
+│   └── my-ai/         #   AI integration
+├── proofs/            # Mechanised core — Coq (solo-core, SessionPi)
+│                      # + Idris2 tracks; STATUS.md is the registry
+├── dialects/          # solo/ and duet/ compilers + examples
+├── _exploratory/      # sidelined scaffolding (me-scaffolding/)
+├── conformance/       # impl ⇄ verified-spec differential tests
+├── spec/              # language specification
+├── grammar.ebnf       # surface grammar
+├── examples/          # example programs
+├── playground/        # demo playground (+ hives/)
+├── my-ssg/            # site generator input
+├── vscode-extension/  # editor support
+├── docs/              # documentation (published via Ddraig SSG)
+├── LICENSE            # MPL-2.0 (code); CC-BY-SA-4.0 for docs
+└── LICENSES/          # full licence texts (REUSE layout)
+....
+
+=== CI gates
+
+* `+proofs.yml+` — machine-checks the Coq solo-core and asserts the
+soundness theorems, the usage-walk checker (R5/R5b), the me→solo
+elaboration (M1), the session-π core (S1.x), and the duet-by-projection
+results (S2) are *axiom-free* (`+Print Assumptions+` must report
+"`Closed under the global context`").
+* `+coverage.yml+` — cargo-llvm-cov over the workspace excluding
+`+my-llvm+`, with an enforced line-coverage floor.
+* `+checker-scaling.yml+` — checker performance scaling gate.
+* `+codeql.yml+`, `+hypatia-scan.yml+`, `+secret-scanner.yml+`,
+`+scorecard.yml+`, `+cflite_*.yml+` — security/fuzzing gates.
+* `+governance.yml+` — estate policy via hyperpolymath/standards
+reusable workflows.
+* `+pages.yml+` — docs deployment via Ddraig SSG.
+
+=== Design principles
+
+* *No proof hole is ever described as "`proved`"* — statement-only
+theorems are tracked obligations (`+proofs/STATUS.md+` vocabulary).
+* *Layered dialects* — features land in the innermost layer that can
+express them; outer layers add, never fork.
+* *Hermetic CI* — the LLVM back end is isolated so every other gate runs
+without a system toolchain.
+
+'''''
+
+_Last updated: 2026-07-27_