# CLAUDE.md
Guidance for working in the `monadify` repository.
## What this is
`monadify` is a **zero-dependency Rust library** of functional-programming
abstractions — Functor, Apply, Applicative, Bind/Monad, Profunctor/Strong/Choice,
plus profunctor-encoded optics. v0.1.1, MIT, edition 2021, MSRV 1.66.
The defining design simulates **Higher-Kinded Types (HKTs)** using Generic
Associated Types: a `Kind` trait with `type Of<Arg>` plus lightweight marker
structs (`OptionKind`, `VecKind`, `ResultKind<E>`, `CFnKind<X>`, `CFnOnceKind<X>`,
`RcFnKind<X>`, `IdentityKind`, `ReaderTKind`). Traits are generic over the *marker*, and
`Self::Of<A>` resolves to the concrete type (e.g. `OptionKind::Of<i32> == Option<i32>`).
Core infrastructure lives in `src/kind_based/kind.rs`.
## Layout
- `src/kind_based/kind.rs` — the `Kind`/`Kind1` traits and all marker structs.
- `src/functor.rs`, `apply.rs`, `applicative.rs`, `monad.rs` — the trait hierarchy
`Functor → Apply → Applicative → Bind/Monad`, defined over Kind markers.
- `src/profunctor.rs` — `Profunctor`/`Strong`/`Choice` and van-Laarhoven optics
(`Lens`/`Getter`/`Fold`, `_1`/`_2`/`_key`, `view`, `lcmap`/`rmap`, `Forget`).
- `src/function.rs` — `CFn`, `RcFn`, `CFnOnce` function wrappers + composition (`>>`/`<<`).
- `src/identity.rs` — `Identity` monad. `src/transformers/reader.rs` — `ReaderT` +
`MonadReader` (`ask`/`local`). `src/utils.rs` — `fn0!`..`fn3!` macros.
- `src/legacy/` — the older associated-type implementation, behind the `legacy`
feature flag (kept for comparison/benchmarking; not the default).
- `tests/{kind,legacy}/` — law-verifying test suites. `benches/compare.rs` —
criterion benchmarks comparing kind-based vs native vs legacy.
Concrete instances implementing the full hierarchy (where lawful): `Option`,
`Result`, `Vec`, `Identity`, `CFn`, `RcFn`, `CFnOnce`, `ReaderT`.
## Conventions
- **Laws are first-class:** every trait documents *and* tests its laws (Functor
identity/composition, Applicative, Monad left/right-identity + associativity,
Profunctor). New instances must add law tests.
- Map/bind closures require `FnMut(A) -> B + Clone + 'static`.
- **Function wrappers:** `CFn` is the unique-ownership, non-`Clone` wrapper (Box-backed).
`RcFn` is the shared-ownership, `Clone`-able alternative (Rc-backed); it re-enables
`lift_a1::<VecKind>` and works in `mdo!`. `CFnOnce` is intentionally non-`Clone`
(FnOnce semantics cannot be cloned). For `Clone`-dependent helpers, use `RcFn` or
bound generically over types that are `Clone`.
- `#![deny(missing_docs)]` is enforced — all public items need docs.
## Quality gates
`scripts/pre-commit.sh` runs `cargo fmt --check`, `cargo clippy --all-features -- -D warnings`,
and `cargo test --all-features`. CI (`.github/workflows/rust.yml`) mirrors these in
separate jobs — `fmt`, `clippy` (`--all-features -- -D warnings`), `test` (default +
`legacy` feature matrix, incl. doc-tests), and an `msrv` job checking against Rust
1.66. The `clippy` job also lints `--benches` so `benches/compare.rs` can't
silently rot. Still **not** enforced in CI (remaining gaps): full
`clippy --all-targets` (the test files have ~50 auto-fixable lints, mostly
`clone_on_copy`) and `cargo doc -D warnings` (one rustdoc link warning).
```bash
cargo test # default kind-based suite
cargo test --features legacy # legacy suite
cargo bench # criterion benchmarks
```
## Memory (Hindsight)
> **MANDATORY (user directive, 2026-06-27):** The Hindsight bank `monadify` is the
> **sole memory of record**. At the **start of every session**, before other work,
> `recall(tags=["project:monadify"])`; at the **end of durable work**, `retain` new
> facts there. Use Hindsight for **all** long-term storage and retrieval — do **not**
> accumulate durable knowledge in the file-based auto-memory (`MEMORY.md`), which
> holds only a one-line breadcrumb pointing here. If the `hindsight` MCP server is
> unavailable (e.g. an unauthenticated headless/cron run), say so explicitly rather
> than silently falling back to file memory.
This project has a dedicated [Hindsight](https://github.com/vectorize-io/hindsight)
memory bank (`monadify`) holding the project's long-term context: git history
(3 epochs — 2022-genesis, 2023-typeclasses, 2025-hkt), architecture/conventions
seeded from this file, and the dependency list. It is exposed as an MCP server
named `hindsight`.
- **Config lives at local scope**, not in the repo — the server URL + bearer
token are in `~/.claude.json` (project-scoped `mcpServers`), so the secret is
never committed. There is intentionally no `.mcp.json` in the tree. To check:
`claude mcp get hindsight`. The MCP tools load automatically at session start.
- **At the start of work, `recall`** relevant context, scoped by tag, e.g.
`recall(query="…", tags=["project:monadify"])`. Useful tags: `source:git-log`
(provenance), `source:CLAUDE.md` (architecture/conventions, `type:directive`),
`source:Cargo.toml` (dependencies); epoch tags like `epoch:2025-hkt`.
- **At the end of durable work, `retain`** new facts with
`tags=["project:monadify", …]` so the bank stays current. Memories tagged
`status:uncommitted` describe in-progress WIP and go stale once committed —
refresh them after committing.
## Babysitter
This project is onboarded for **babysitter** orchestration; the project profile
lives at `.a5c/project-profile.json` (written by `project-install`).
### Methodology
- **Primary — hypothesis-driven-development:** treat every typeclass law (Functor
identity/composition, Applicative, Monad left/right-identity + associativity,
Profunctor) as a falsifiable hypothesis and verify it with property-based tests
(`proptest`) across generated inputs, layered on the existing example-based law
tests. Use this for the top correctness/law-coverage goal.
- **Backbone — atdd-tdd:** write the law/property test first (RED), then implement
the instance (GREEN), matching the project rule that an instance ships with its
matching law test. Use for every new trait impl or concrete instance.
- **For big changes — evolutionary:** drive encoding/typeclass changes as small,
reviewable, law-test-green increments instead of big-bang 26–50 file rewrites.
Use when touching the high-churn core trait hierarchy or the HKT encoding.
### Recommended skills / agents
Must-have skills: **rust-testing** (proptest/property patterns + coverage),
**tdd** (write-test-first enforcement), **verify** (one-shot fmt + clippy
`--all-targets` + default/legacy test matrix + MSRV + doc build), **rust-patterns**
(idiomatic Rust/GAT/trait-bound guidance, incl. the `CFn`-not-`Clone` constraint),
**rust-review** (ownership/lifetime/coherence review of core trait edits).
Must-have agents: **tdd-guide** (drives the law-test-first loop), **test-generator**
(generates property/law tests for new and existing instances), **rust-reviewer**
(mandatory review of the high-churn core trait files), **rust-build-resolver**
(minimal-diff fixes for cargo/borrow-checker/feature-matrix breakage),
**architect** (designs around `CFn`-not-`Clone` and shapes new transformers
like StateT/WriterT before coding).
### Autonomy
**Semi-autonomous:** proceed on routine work (research, tests, refactors, docs),
but break for review at phase boundaries and before commits to `main`. ALWAYS
break on destructive-git operations and crates.io publish/release.
### CI/CD
Babysitter is kept **LOCAL / on-demand** — it is intentionally NOT wired into
GitHub Actions. The existing `.github/workflows/rust.yml` remains the automated
Rust quality gate (fmt, clippy, default+legacy test matrix, MSRV 1.66).
### How to run
- `/babysitter:babysit` — orchestrate a run (or use the babysitter CLI).
- `/babysitter:plan` — plan a run without executing it.