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, 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. Preserve tricu's unique intensional strengths rather than assuming conventional language features are the answer.

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. Describe behavior affirmatively in documentation and comments. Use contrasts with excluded behavior only when a positive description cannot accurately convey the distinction.

Document supported usage, semantics, implementation contracts, and reproducible validation procedures; keep implementation details beside source/tests. Do not present unvalidated changes as shipped behavior.

Use YYYY.MM.DD CalVer in tricu.cabal

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

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.

In public examples, prefer indented continuation and unwrapped let, case, and do blocks over layout-only parentheses. Use <| or |> when they make nested calls clearer. Keep parentheses where syntax requires them or grouping is the clearest explanation; do not contort code just to eliminate them. Both pipe chains associate left-to-right, so repeated <| is not nested application.

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