AI.djot

# AI Assistant Specification

## Machine-Readable Artefacts

The `.machine_readable/` directory contains structured metadata required for automated reasoning and project introspection.

- `STATE.scm`: Current project state, milestones, and progress.
- `META.scm`: Architecture decisions, development methodology, and rationale.
- `ECOSYSTEM.scm`: Ecosystem placement, upstream/downstream relationships, and interoperability.
- `AGENTIC.scm`: AI agent interaction patterns, affordances, and constraints.
- `NEUROSYM.scm`: Neurosymbolic integration configuration and hybrid reasoning settings.
- `PLAYBOOK.scm`: Operational runbook, workflows, and incident procedures.

Additional artefact:

- `AI.djot`: AI Assistant behavioural and operational instructions.

## Repository Roots

- Local repository root: `/var/mnt/eclipse/repos`
- Remote mapping: `https://github.com/hyperpolymath/<name>`
- Repository names are lowercase; dots (`.`) are replaced with hyphens (`-`).
- If a repository is missing locally, check the remote and synchronize before proceeding.

## AI CLI Standards

- Include `ai-cli-crash-capture/` and `contractiles/` from this template in all new repositories.
- Mirror all 6SCM files into `.machine_readable/6scm/`.
- Before generating code, inspect `/var/mnt/eclipse/repos/proven` for the current Idris “unbreakable” library status.
- If the project depends on the unbreakable Idris library, add an *Idris Inside* badge to the repository.
- When new bindings are required, create them under `/var/mnt/eclipse/repos/proven` using the naming pattern `idris2-zig-<language>`.
- If new code implies additional unbreakable Idris modules, add them to `/var/mnt/eclipse/repos/proven` and update binders across all supported languages.

## Language Policy

### Allowed Languages and Tools

| Language/Tool | Use Case | Notes |
|---------------|----------|-------|
| ReScript | Application code | Type-safe, compiles to JS |
| Deno | Runtime and package management | Replaces Node/npm/bun |
| Rust | Systems, performance-critical, WASM | Preferred for CLI tools |
| Tauri 2.0+ | Mobile apps (iOS/Android) | Rust backend + web UI |
| Dioxus | Mobile apps (native UI) | Pure Rust, React-like |
| Gleam | Backend services | BEAM or JS targets |
| Bash/POSIX Shell | Automation scripts | Keep minimal |
| JavaScript | Only where ReScript cannot | MCP glue, Deno APIs |
| Nickel | Configuration | Complex config logic |
| Guile Scheme | Metadata/state files | For all `.scm` artefacts |
| Julia | Batch/data processing | Per RSR |
| OCaml | AffineScript compiler | Language-specific |
| Ada | Safety-critical systems | Where required |

### Banned Languages and Tools

| Banned | Replacement |
|--------|-------------|
| TypeScript | ReScript |
| Node.js | Deno |
| npm | Deno |
| Bun | Deno |
| pnpm/yarn | Deno |
| Go | Rust |
| Python | Julia / Rust / ReScript |
| Java/Kotlin | Rust / Tauri / Dioxus |
| Swift | Tauri / Dioxus |
| React Native | Tauri / Dioxus |
| Flutter/Dart | Tauri / Dioxus |

## Mobile Development Policy

A strict Rust-first approach applies.

- Use **Tauri 2.0+** for web UI (ReScript) + Rust backend.
- Use **Dioxus** for pure Rust native UI.

Both are FOSS with independent governance.

## Enforcement Rules

- Do not create new TypeScript files; convert existing TS to ReScript.
- Do not use `package.json` for runtime dependencies; use `deno.json` imports.
- Do not include `node_modules` in production; Deno handles dependency caching.
- Do not use Go; use Rust.
- Do not use Python; use Julia (data/batch), Rust (systems), or ReScript (apps).
- Do not use Kotlin/Swift; use Tauri 2.0+ or Dioxus for mobile.

## Package Management

- Primary: Guix (`guix.scm`)
- Fallback: Nix (`flake.nix`)
- JavaScript dependencies: Deno (`deno.json` imports)

## Security Requirements

- Do not use MD5 or SHA-1; use SHA-256 or stronger.
- Use HTTPS only.
- Do not hardcode secrets.
- Pin all dependencies by SHA.
- Include SPDX license headers in all files.