docs: update README and roadmap with new directory structure

- Updated project structure documentation
- Added contractiles/must/ and must runner info
- Updated resource paths for reorganized docs
- Added references to SCM checkpoint files

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: Test

README.adoc

@@ -86,34 +86,96 @@ cd src/ffi/wasm && wasm-pack build --target web
 
 ```bash
 wokelang/
-├── docs/               # Theory docs (EBNF, semantics, etc.)
-├── src/
-│   ├── lexer.mll       # Lexer (OCaml)
-│   ├── parser.mly      # Parser (Menhir)
-│   ├── ast.ml          # Abstract Syntax Tree
-│   ├── types.ml        # Type checker
-│   ├── eval.ml         # Interpreter
-│   ├── repl.ml         # REPL
-│   └── ffi/            # FFI bindings
-│       ├── vyper/      # Vyper contracts + ABI bindings
-│       │   ├── contracts/
-│       │   ├── abi/
-│       │   └── bindings/
-│       └── wasm/       # WASM (wasm-pack)
-├── examples/
-│   ├── hello.wl        # Hello World
-│   ├── fib.wl          # Fibonacci
-│   └── gratitude_blockchain.wl  # Vyper integration
-├── tests/              # Test cases
+├── .bot_directives/     # Bot constraint files for gitbot-fleet
+├── .claude/             # Project-specific AI instructions
+├── .github/workflows/   # CI/CD (Hypatia, CodeQL, Scorecard)
+├── .machine_readable/   # Machine-readable metadata
+│   └── 6scm/           # SCM checkpoint files
+├── contractiles/        # Contractile definitions
+│   ├── dust/           # External dependencies
+│   ├── k9/             # Security constraints
+│   ├── lust/           # Desired features
+│   ├── must/           # Required features & must runner
+│   └── trust/          # Trust boundaries
+├── docs/               # Documentation
+│   ├── architecture/   # Architecture docs (COMPILER-ROADMAP.adoc)
+│   ├── sessions/       # Development session reports
+│   ├── ABI-FFI-README.adoc        # ABI/FFI integration guide
+│   ├── DEPLOYMENT.adoc            # Deployment documentation
+│   ├── GAP-ANALYSIS.adoc          # Implementation gaps
+│   ├── NEXT-STEPS.adoc            # Development roadmap
+│   ├── PALIMPSEST.adoc            # License philosophy
+│   ├── PROVEN.md                  # proven library integration
+│   └── WORKERS.adoc               # Worker documentation
+├── examples/           # Example WokeLang programs
+├── ffi/
+│   └── zig/           # Zig FFI implementation (C ABI)
+│       └── src/
+├── license/            # License files
+│   └── PMPL-1.0-or-later.txt
 ├── scripts/
-│   ├── setup.sh        # Setup script
-│   └── build.sh        # Build script
-├── .devcontainer/       # VS Code Dev Container
-├── .github/workflows/   # GitHub Actions CI/CD
-├── Cargo.toml           # Rust dependencies
-├── dune                # OCaml build system
-├── dune-project
-└── README.md           # This file
+│   ├── install-hooks.sh  # Install git hooks
+│   └── setup.sh          # Setup script
+├── site/               # wokelang.org website
+│   ├── content/        # Markdown content
+│   ├── templates/      # Tera templates
+│   └── config.yaml     # Site configuration
+├── src/
+│   ├── abi/            # Idris2 ABI definitions with formal proofs
+│   │   ├── Foreign.idr
+│   │   ├── Layout.idr
+│   │   └── Types.idr
+│   ├── ast/            # Abstract Syntax Tree
+│   ├── interpreter/    # Tree-walking interpreter
+│   ├── lexer/          # Token generation (logos)
+│   ├── parser/         # Parser (tokens → AST)
+│   ├── stdlib/         # Standard library modules
+│   │   ├── array.rs
+│   │   ├── chan.rs     # Go-style channels
+│   │   ├── io.rs       # File I/O with consent
+│   │   ├── math.rs
+│   │   ├── net.rs      # HTTP with consent
+│   │   ├── string.rs
+│   │   └── time.rs
+│   ├── typechecker/    # Hindley-Milner type inference
+│   ├── vm/             # Bytecode VM
+│   │   ├── bytecode.rs
+│   │   ├── compiler.rs
+│   │   ├── machine.rs
+│   │   └── optimizer.rs
+│   ├── main.rs         # CLI entry point
+│   └── repl.rs         # REPL
+├── tests/              # Test suite
+├── .tool-versions      # asdf tool versions (rust, deno, idris2, zig)
+├── AI.a2ml             # AI assistant instructions
+├── Cargo.toml          # Rust dependencies
+├── ECOSYSTEM.scm       # Ecosystem relationships
+├── META.scm            # Architectural decisions
+├── STATE.scm           # Current project state
+└── README.adoc         # This file
+
+## 🛠 Development
+
+### Must Runner (Contractile Enforcement)
+
+WokeLang uses a **Mustfile** (in `contractiles/must/`) to enforce mandatory checks:
+
+```bash
+# Run all mandatory checks (security, tests, format)
+must run
+
+# Individual checks
+just lint    # Security checks
+just test    # Test suite
+just fmt     # Code formatting
+```
+
+**Mustfile** defines requirements that MUST pass before commits/releases. See `contractiles/` for full contractile system:
+- `must/` - Mandatory requirements (MUST pass)
+- `lust/` - Desired features (WANT to have)
+- `dust/` - External dependencies
+- `trust/` - Trust boundaries
+- `k9/` - Security constraints
 
 ## 🛠 Development
 

docs/architecture/COMPILER-ROADMAP.adoc

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
 # WokeLang Compiler Roadmap
 
 ## Current Status (2026-01-31)
@@ -311,10 +312,15 @@ See the task list above for areas that need work. The highest priority items are
 
 ## Resources
 
-- **ABI/FFI Documentation**: `ABI-FFI-README.md`
+- **ABI/FFI Documentation**: `docs/ABI-FFI-README.adoc`
 - **Bytecode Specification**: `src/vm/bytecode.rs`
 - **Example Programs**: `examples/`
 - **Language Specification**: `docs/` (TODO)
+- **proven Integration**: `docs/PROVEN.md`
+- **Project State**: `STATE.scm`
+- **Ecosystem**: `ECOSYSTEM.scm`
+- **Architecture Decisions**: `META.scm`
+- **Development Sessions**: `docs/sessions/`
 
 ## Estimated Timeline to v0.1