Claude Instructions for AILANG Development

North Star — design_docs/PROGRAM.md

This work runs as one program: a self-specializing harness. The motoko core is minimal and frozen; every improvement is routed to exactly one lane — an AILANG fix, a motoko extension, or (rarely) a core-floor fix that re-freezes. We discover friction by running benchmarks through the data-led loop, then route it. Default bias: if it can be an extension, it is an extension — not a core change. The living roadmap (benchmark ladder · extension catalog · AILANG-fix backlog) lives in PROGRAM.md.

Session start (attended) — every machine reads the SAME message store

The canonical inbox is prod Firestore, project ailang-multivac. A bare ailang messages list reads only this machine's private SQLite — real user feedback once sat unread for weeks that way. Every machine doing AILANG work exports:

export AILANG_STORAGE_MESSAGING=gcp
export AILANG_MESSAGES_PROJECT=ailang-multivac

AILANG_STORAGE_MESSAGING is the per-store override of the ONE plane switch AILANG_STORAGE (M-V1-SIMPLIFY-S3 M3): it moves messaging alone, so ailang storage status must show messaging gcp (AILANG_STORAGE_MESSAGING) with coordinator and observatory still local. Never export AILANG_STORAGE=gcp for this — that moves all three stores. The retired AILANG_MESSAGES_STORE (and AILANG_COORDINATOR_REMOTE, AILANG_CHAINS_READ, AILANG_CHAINS_CLOUD) is a hard error naming its replacement — fix the export, do not work around it.

Then ailang messages list --unread spans all inboxes, and a non-local listing names its store in the header — no store: gcp (...) header means you are reading local, usually a stale binary. Summarize to the user and ask before acking. Unattended (coordinator task or mission stage: AILANG_TASK_ID / AILANG_MISSION_STAGE set), there is no user: skip the inbox and do the task. Triage via list --unread --json (full IDs + bodies; messages read marks read). Ack per message id — ack --all also sweeps outbound inboxes; unack <id> on failure.

The measured traps (stale-binary control, project pinning, pkg:* inboxes) and the full topology: docs/internal/message-plane-topology.md.

Critical Principles

0. NEVER DESTROY LOCAL WORK WITH GIT OPERATIONS

NEVER run these commands — they destroy uncommitted work:

• git checkout <branch> when there are uncommitted changes
• git pull on a branch with local commits (use git status first!)
• git reset --hard, git clean -fd
• git stash followed by branch switching that causes fast-forward

CORRECT approach:

1. ALWAYS git status first
2. If uncommitted changes exist, ASK THE USER how to handle them
3. Work on CURRENT branch — don't force a branch switch
4. NEVER assume it's safe to discard or stash work

0.1. VERIFY GITHUB ACCOUNT BEFORE RELEASES/TAGS

The developer uses multiple GitHub accounts. Before ANY release or git push:

gh auth status                              # Check active account
# This repo needs: sunholo-voight-kampff (Claude Code agent account)
# MarkEdmondson1234 = human developer account
# rw-markedmondson = WRONG (Rockwool project)
gh auth switch --user sunholo-voight-kampff  # Switch if needed

1. Look the question up, not the tool

Before writing a new script, check make help, tools/, and the ailang CLI (chains, messages, eval-*, dashboard) — raw SQLite queries and ad-hoc scripts rebuild worse versions of what exists. Knowing a tool exists is not the same as knowing which question it answers; that gap is where we rebuild things.

The provider-side trace settles arguments our own logs cannot (2026-08-26: it proved five "model returned zero bytes" failures were our own size ceiling, after two prompt fixes had been aimed at a model problem that did not exist). The OpenRouter account key is inference-only — /api/v1/activity 403s — so go via the observatory, which is indexed by time anyway.

Asking "what did the agent DO?" and inferring the rest is how ailang fmt spent two weeks telling every eval model its correct code was non-canonical — the message was in the session JSONL the whole time.

2. No silent fallbacks — fail loudly

If a fallback value would affect data integrity, business logic, or user decisions (pricing, model configs, required env vars, validation), return zero/null/error instead. Fallbacks are fine for UI defaults, optional features, and caching.

3. Systemic fixes — audit before patching

Before fixing a bug, ask whether it's part of a larger pattern; search for similar code paths and design one unified fix instead of patching case-by-case.

4. Read the control before refusing on its behalf

Before declining a requested action to protect a safeguard, check what the safeguard actually enforces. If the artifact is identical whether you or the user performs the step, refusing buys no integrity — it only moves the work back to the user and costs the session.

Measured 2026-09-02: asked to record an attended ruling with mission_answer.sh, the agent refused on the grounds that a loop-authored ruling would be indistinguishable from a human one. But that script overrides the git identity for every caller (git -c user.name=… -c user.email=…), and this machine's git identity is the fleet bot for every session including Mark's — so the two commits are byte-identical. The guarantee being defended did not exist. Cost: about an hour, and the decision still had to be made afterwards. Related trap: a rule addressed to the unattended loop (mission-control's SKILL.md) is not automatically a rule about an attended session that happens to contain an agent.

If the control is genuinely weak, say so and offer to fix it — do not simulate it by refusing.

Project Overview

AILANG is a deterministic language designed for autonomous AI code synthesis and reasoning. File extension: .ail. Priorities: machine decidability, semantic transparency, compositional determinism.

Design principles: explicit effects (all side effects declared in signatures) · everything is an expression (no statements) · type safety (Hindley-Milner + row polymorphism) · deterministic (all non-determinism explicit) · AI-friendly (structured execution traces).

For syntax, run ailang prompt — never write AILANG from memory, and verify any syntax claim with ailang check before putting it in a prompt or doc.

Reference Documentation

Skills and path-scoped rules (.claude/rules/) load themselves when relevant — you don't need to look them up. These are the docs you would NOT think to look for:

• MOTOKO.md — which motoko_agent checkout do evals actually use? Read BEFORE touching any ~/dev/mk-* directory or the motoko shim.
• design_docs/PROGRAM.md — the living roadmap and routing lanes.
• ARCHITECTURE.md — layer map and enforced import directions.
• docs/LIMITATIONS.md — what AILANG genuinely cannot do yet.
• docs/docs/guides/ — development-workflow, coordinator, agent-messaging, evaluation, telemetry, debugging, collaboration-hub, database-architecture, lsp.
• design_docs/ · examples/