AGENTS.md - tricu Project Guide

For AI agents and contributors working in this repository.

North star

Always aim to make writing practical programs in tricu better. Judge self-hosting, contracts, typed fragments, and tree-calculus-specific ideas by what they enable people to write, run, debug, and maintain—not by architectural milestones alone. Test ideas on real programs, measure their costs, and state safety and performance limits honestly. Preserve tricu's unique intensional strengths rather than assuming conventional language features are the answer.

Research status

There is no legacy code, stable API, or human consumer. Replace flawed abstractions rather than preserving them for compatibility. Historical behavior is evidence, not automatically the specification: classify differences as intended requirements, bugs, or deliberately retired behavior. State corrections explicitly, update callers and independent expectations, and retain negative/security controls. Git makes source experiments reversible; retained accepted toolchains provide executable rollback. Neither replaces testing.

Documentation discipline

docs/ is for durable documentation, never work-in-progress notes. Do not put agent progress reports, provisional findings, in-flight plans, merge/generation reminders, handoff notes, or scratch investigations there—even inside an existing guide. Keep those in conversation, commit messages, or external scratch artifacts. Document supported usage, semantics, implementation contracts, and reproducible validation procedures; keep implementation details beside source/tests. Do not present unvalidated changes as shipped behavior.

Build & Test

For tricu compiler build/run commands and focused checks, use docs/build-and-run.md. Keep usage in the guides linked there, semantics in the language contract, and implementation details beside source/tests. Do not add parallel status/roadmap/runbook documents for each implementation slice.

# Tests
nix flake check

# Build tricu executable
nix build .#

Compiler checkpoint completion includes cleanup

A verified generation-two compiler is not a finished development checkpoint until rolling retention is complete. After pair acceptance and smokes, run the tracked test/bootstrap_retention.py plan/apply/check workflow in compiler rebuilding. Keep explicitly selected current and rollback toolchains, their frozen inputs, current support preparation, and registered Nix runtime roots. Prune superseded scratch objects in the same checkpoint; do not defer this to a future agent. The completion check must pass before declaring the checkpoint finished or starting the next feature batch. If cleanup is blocked, report the blocker and outstanding bytes as an incomplete checkpoint. Recovery archives are never routine scratch-cleanup targets. Do not implement retention tooling in ignored scratch.

Never call cabal directly

Rule of thumb: if it builds, links, or tests, it goes through nix.

Project Overview

tricu (pronounced "tree-shoe") is a programming-language experiment written primarily in Haskell.

Runtime trees and reduction are in src/Runtime/Tree.hs; src/Runtime.hs is the source-free host API. Source compilation belongs to the portable tricu compiler; the historical Haskell frontend has been removed.

File extensions

• .hs - Haskell source
• .tri - tricu language source (used in lib/, test/, demos/)
• .arboricx - Portable executable bundle
• .dag - Serialized kernel DAG (used by gen_kernel.zig at build time)

Haskell tests

Tests live in test/Spec.hs and use Tasty + HUnit.

nix flake check

tricu Language Quick Reference

Before authoring or rewriting .tri, read the language-feature inventory. Check available syntax and library protocols before proposing new machinery or claiming a language gap; verify uncertain behavior with the selected stable compiler.

t                      → Leaf (the base term)
t t                    → Stem Leaf
t t t                  → Fork Leaf Leaf

x = t                  → Define term x = Leaf
id = (a : a)           → Lambda identity (eliminates to tree calculus)
head (map f xs)        → From lib/base.tri

!import module as NS    → Import workspace module under namespace

-- line comment

Agent Coordination

You are only permitted to use intercom or agent orchestration tools available to you with explicit user approval.