Lettuce Documentation

The first successful path is fewer than five commands.

lettuce init --author jota --bootstrap-author --bootstrap-project default
lettuce task create LET-1 --project default --author jota --title "Try lettuce" --body "First task."
lettuce task list --project default
lettuce task show default/LET-1 --with-body

default is just an ordinary project name — there is no hidden default-project pointer and no project inference from store contents. Pass --project and --author explicitly for mutations; lettuce never infers them from the OS, Git config, or store contents.

Naming guidance

• Task IDs: a short uppercase prefix related to the project, e.g. API-42, LAT-7. v0.15 does not enforce prefix/project coupling (that would make rename and import workflows harder).
• Agent authors: stable, non-secret identifiers such as codex-local-01, ci-agent, planner-agent.

The core agent loop

Once a store exists, an agent typically:

1. Discovers work — lettuce task list / lettuce query run (FQL). 2. Claims it — lettuce lease acquire (atomic, expiring). 3. Transitions status — lettuce task transition (validated). 4. Records execution — lettuce run start / run finish, artifact add. 5. Validates — lettuce validate --strict and lettuce doctor --format json.

Modes

• filesystem (default) — offline, canonical state under the store root.
• dedicated-git — a strongly-consistent shared store that fetches upstream before every mutation (requires connectivity by design; not an offline mode).
• client — set a server URL (and bearer token) to drive a running lettuce serve over HTTP instead of mounting the store.

Next

• What is lettuce · Why lettuce
• Command Reference — every command, with flags and examples.

The source-of-truth knowledge bundle for lettuce, maintained in the lettuce repository itself. It has two layers:

• Curated — concepts, guides, and orientation, authored by humans/agents and gated by okf check.
• Generated — the Command Reference, emitted from the binary by lettuce usage --format okf and regenerated by make docs. Never hand-edit anything under reference/.

Orientation

• What is lettuce
• Why lettuce (and not just Markdown + a convention)
• Getting started

Concepts

• The store and the two data planes
• Tasks and the work plane
• Workflow — states, transitions, and gates
• Cells — the coverage model
• Dimensions and members
• Methodology catalog — the orientation board
• Scopes — the DoD/board partition
• The shipped convention — coverage as data
• Milestones and Definition of Done
• Querying with FQL
• Graphs — authored process, enacted on the ledger

Guides

Agent Playbook — do-this-now guides for driving lettuce at full power:

• First contact — what a fresh agent sees, reads, and does
• Project setup playbook — prepare a project to leverage lettuce
• Agentic loop demo — one development cycle, step by step

Reference guides:

• Running lettuce in autonomous agentic cycles
• Configuring lettuce for useful leverage
• How to read lettuce — orienting in an existing store
• Serving lettuce safely (HTTP)
• Driving lettuce from a file: structured external input
• Retrying a mutation safely: --idempotency-key

Reference (generated)

• Command Reference — the exhaustive CLI surface, regenerated from the binary by make docs.

lettuce is a local-first, filesystem-native work tracker and coverage/quality store for humans, agents, and small technical teams that need inspectable work state. Canonical state — projects, tasks, comments, runs, artifacts, cells — lives as ordinary files inside a path-jailed store root. Every mutation is validated and recorded as an event. The same binary is a CLI and an HTTP server, and the same CLI becomes an HTTP client when a server URL is set.

Thesis

Most work trackers optimize for hosted workflows and opaque databases. lettuce optimizes for the opposite:

• plain files that can be inspected and reviewed
• deterministic validation before and after mutations
• stable task references for agents and automation
• Git-friendly history for dedicated stores
• structured diagnostics that explain repair paths
• CLI-first workflows before server or UI complexity
• HTTP-client mode for agents that should not mount the canonical store

Why filesystem-native

The filesystem is the product boundary. Because canonical state is ordinary files, users and agents can review exact changed paths, validate state without a running server, recover interrupted local work, attach Git history to each mutation (in dedicated-git mode), and debug with normal shell tools. This is a deliberate tradeoff: lettuce is not a high-volume database, a real-time collaboration server, or a dashboard-first planning suite in v0.15.

Who it's for

• Solo engineers — create a local store, track tasks, query current work, optionally review changes through Git.
• Agents — discover work, claim it with leases, record execution runs, attach artifacts, and act on structured diagnostics without editing canonical files directly.
• Small teams — project-local work state with explicit author attribution, optional HTTP authorization, and reviewable mutations.
• Tool integrators — stable JSON envelopes, diagnostic codes, and filesystem fixtures over a hosted UI.

Next

• Why lettuce and not just Markdown — the determinism argument.
• Getting started — your first store in under five commands.
• Command Reference — the complete 152-command surface.

A Markdown board in your repo is only as honest as the agent editing it. An agent can write done or hardened with nothing behind it, and the next reader believes it. lettuce moves the guarantee from instruction-following to code.

• State transitions are validated, not requested. A task moves between states only along declared, legal transitions; an illegal move is refused, not recorded.
• Leases are atomic, expiring, and audited — not a naming convention. Two agents cannot both believe they hold the same work.
• A coverage cell cannot reach hardened — or earn hardening depth — without linked evidence. By default the tool refuses the write; the one deliberate exception, --facilitate, proceeds past a failed gate but records the failed verdict on the ledger, so a green that was not earned is visible rather than silent. And the gate establishes provenance — the green traces to a completed, graph-backed ticket — not proof that the cell's subject was actually checked.

The store is still ordinary text: greppable, diffable, exportable. But what that text claims is enforced by the binary, not by the goodwill of whoever wrote it. That is the whole point — determinism over "please follow the convention."

If a rule in CLAUDE.md reliably did the job, you would not need lettuce. You reach for lettuce when verified must mean proven, not merely asserted.

Consequence for autonomous agents

Because claims are enforced, an autonomous loop can trust the store as its orientation and evidence substrate: it can ask "what is unfinished and provable?" and act on the answer without a human re-checking every assertion. See the core agent loop and Command Reference.

The coverage plane grades how proven each part of a product is — and, read the other way, what work remains. It is lettuce's defining capability beyond a task list.

Vocabulary

• Convention — coverage, the convention-as-data lettuce ships: states, transitions, gates, dimensions, families. Bundled in the binary and active on every project by default; you inspect it and tune it per project with the defaults layer rather than swapping it.
• Dimension — one quality axis (e.g. test-coverage, input-validation). Grouped into families; each has an applicability (universal | conditional) and is closed (fixed members) or open (members minted ad-hoc). A project's effective dimensions = the pack's ⊕ an additive project runtime layer (dimension declare; never shadows pack vocab).
• Member — one enumerated value of a dimension: {slug, name, description, rank} (empty name renders as slug; rank 0 = unranked, sorts by slug).
• Cell — one sparse, evidence-asserted point: a canonical coordinate (dim=member;dim=member — pairs sorted by dimension, duplicates rejected, slugs validated) carrying one state from the active pack. An untouched coordinate is not stored; it reads as the pack default with stored=false.
• State / grade — pack states carry a category (open, in-progress, review, done, excluded, flagged) that drives engine-enforced honesty invariants: only done counts as green; excluded leaves the denominator; review states never count as done; machine-only transitions (e.g. regress) fire only via the sanctioned path (cell reconcile).
• Gate — authorizes a gated transition. Built-in evaluators: guard-bite (the cell has ≥1 AUTHORISING evidence link: --kind task, citing a task that is done and carries custom/grc, the pin of its verified close walk; a --kind url link annotates but never authorises) and consistency (store predicates recompute clean). cell transition refuses a gated move that fails its gate (FW-WF-GATE-UNSATISFIED) unless --facilitate (records the verdict but allows the move).
• Evidence — links on an asserted cell (--kind task = validated task ref, --kind url = opaque string). cell reconcile machine-regresses stale-green cells whose cited evidence no longer resolves.

Two readings: proof and roadmap

The same cells serve a backward and a forward reading. Backward, a cell is proof — quality already earned. Forward, each coordinate is a point in the product's quality space and every thin cell is work waiting to happen:

| Grade (coverage pack) | Forward meaning | |---|---| | untested (or unstored) | not yet discovered or decided | | gap | a known deficiency — a decided TODO | | smoke | shallow proof needing deepening | | hardened | done — a committed guard provably bites | | excluded | decided out of scope (leaves the denominator) |

The grade ladder is thus also a work-discovery ladder, and the board is a roadmap: an agent picks its next target from the frontier of weak coverage (cell rollup for the weakest axes/members, board export for the whole frontier), does the work as a task on the work plane, then closes the loop by linking that task as evidence and grading the cell. Work hardens cells; cells reveal work.

Stored cells vs the declared grid (implicit cells)

Storage stays sparse: only coordinates you explicitly assert are written to disk (cell list enumerates exactly those; the pack-default space is never materialised). Left alone, that makes the coverage denominator the count of stored cells — so a scope with one hardened cell and nothing else reads 1/1 = 100%, a vacuous "done". A declared grid fixes that.

A grid is declared per scope as two axes of member slugs — its units (rows, the things being covered) and its applicable dims (cols) — and the scope's honest denominator becomes their cross-product |units| × |dims|. Every un-worked coordinate in that space is an implicit cell: not stored, but counted in the denominator, reading as the pack default (e.g. untested). You record real progress against a fixed grid instead of minting cells one at a time.

lettuce grid scope add-unit s1 validate recover      --project P --author A
lettuce grid scope add-dim  s1 functional resilience --project P --author A
lettuce grid show --project P            # every scope's units/dims/size + project denominator
lettuce cell rollup --by scope --project P   # s1 → untested 0/4 (four implicit cells)
lettuce cell set "scope=s1;unit=validate;dim=functional" --state hardened --project P --author A
lettuce cell rollup --by scope --project P   # s1 → untested 1/4 (one stored, three implicit)

Behaviour to know:

• Both axes required. A scope with units but no applicable dims (or the reverse) has size 0 and contributes nothing to the denominator — a half-declared grid never reads a vacuous ratio.
• In-grid only. Once a grid governs a scope, a stored cell counts only if its unit= member is a declared row and its dim= member a declared col; off-grid coordinates never move the applicable / hardened / DoD numbers. The rendered board follows the same partition (LET-531): an off-grid cell is not drawn as a grid row and never reaches the panel's "N hardened of M testable"; the panel announces the count with lettuce grid scope show SCOPE instead.
• Backward-compatible. A project with no grid/ subtree reads declared=false and every consumer (cell rollup, board, dod) falls back to the observed stored-cell denominator — the pre-grid behaviour.
• One denominator, every surface. cell rollup, board export, board next, board render and the DoD verdict all read the same declared applicable space, so they cannot disagree. board next also lists the un-worked grid coordinates as implicit-untested open cells; the rendered heatmap draws rows only for units that hold a stored in-grid cell.

Freshness and depth — is a green cell's proof still current?

A hardened cell answers "was this proven?" — but proof decays as the code moves on. Two derived, never-stored signals disclose whether a green cell's evidence is still trustworthy, and both feed the Definition of Done:

• Freshness (FRESH-3) — a categorical recency bucket, fresh | aging | stale, computed per cell at read time. Crucially it is measured in store revisions, NOT wall-clock time: distance = current store revision − the revision the cell's evidence was last asserted at, where the store's revision is its event count (rev@N — the same counter the board masthead uses), and the distance is clamped at 0 (an anchor ahead of the reference reads fresh, never "future-stale"). The default window: fresh within 50 revisions of the assertion (≈ one working wave), aging past 50 but within 2× (≤100 — a re-check is advised), stale beyond 100 (a re-check is due). It is a pure function of that distance — derived on every read, never persisted (a stored value could drift out of sync; a derivation cannot lie).
• Basis — alongside the bucket each cell discloses whether its freshness is observed (the cell has a real revision anchor — an evidence link carrying an asserted revision) or presumed (no anchor at all → it is anchored at store genesis, so it reads maximally distant). Presumed is the honest "this cell never once bound its currency to a store revision"; a presumed cell counts as unknown against a recency floor, remedied by re-affirming with real evidence.
• Depth (FRESH-2) — how many distinct store revisions have independently confirmed the grade (via cell verify / cell affirm). Confirming twice at the same revision buys no depth (the anti-farming rule); a verify earns strong depth only when it carries per-cell --evidence (the anti-rubber-stamp rule).

The DoD's optional --recency fresh|aging and --depth N floors gate on these signals (see Milestones & DoD). Recency is this one revision-distance measure — there is nothing to select or configure; the way it is computed is fixed.

The coverage ladder

Every project runs the shipped coverage convention by default; its grade ladder is:

| Grade ladder (default → … → done) | Meaning | |---|---| | untested → planned → in_progress → gap → evidence_linked → smoke → hardened; blocked, regressed (flagged); excluded, waived (excluded) | lettuce's own 88-dimension quality taxonomy; harden is guard-bite-gated (a committed guard that provably bites under fault-injection); waive requires a reason |

* = the default an untouched coordinate reads as (on a fresh project, untested). You do not swap the convention; you tune it per project with the defaults layer.

Coverage: 88 dimensions in 15 families

Inspect any with lettuce dimension list --project P (or dimension show <slug> --project P for one axis).

| Family | Dimensions | |---|---| | correctness | A functional · C spec-impl fidelity · N domain-model · O compat/migration · Q release-compat · U internal consistency | | usability | B UX/DX · S self-documentation · T error-messaging · M docs & examples · AY accessibility · BI i18n/l10n · VD visual & product design · AX agent experience · KB knowledge-base quality · WL white-label · BC browser-compat | | interface | H HTTP/API · J import/export round-trip · BX agent-readiness · CB multichannel parity · AP agent-protocol interop · DP data portability | | security | I attack surface · V privacy · AO rate-limiting · AZ bounded resources · BD auditability · RT red teaming · PT purple teaming · TM threat modeling · RC regulatory compliance | | reliability | BZ temporal · D data integrity · E resilience · F concurrency · FP cross-process concurrency · EL service liveness · AM idempotency · CC cleanup · AN backup/DR · AT determinism · OP ops & incident response | | distributed | G multi-node/sync · CA storage-backend equivalence | | performance | L performance · P observability · SC scalability patterns · DT distributed tracing | | maintainability | K code-quality · AA maintainability · AB testability · R configurability · BL architecture · CS code smells | | delivery | AC licensing · AR supply-chain/SBOM · AS deploy/release · BM CI-CD · BN packaging · BY stack maturity · BP cross-platform portability · LG legal, IP & terms · CN cloud-native/k8s · RG reproducible generation & provenance | | process | TD TDD discipline · GQ quality-gate quality · TK tracking & board discipline · QA QA procedure · RV adversarial/peer review · AL agentic dev-loop quality · PM process maturity & artifacts · RQ research & inquiry quality | | product | PA product analytics & north-star · XP experimentation & A/B testing · PD product discovery & prioritization | | growth | PR pricing & packaging · MN revenue, billing & unit economics | | customer | ON onboarding & activation · SU customer support & service · CX success, retention & churn · FB feedback & voice-of-customer | | market | PO positioning & messaging · DG demand generation & campaigns · SE content, SEO & GEO/AEO discoverability · IR investor & stakeholder communications | | lifecycle | FO cloud cost & FinOps efficiency · SN deprecation, EOL & sunset |

Worked example

lettuce cell set "area=auth;layer=api" --state in_progress --project "$P" --author "$A"
lettuce cell evidence add "area=auth;layer=api" --ref "$P/TASK-1" --kind task --project "$P" --author "$A"
lettuce cell transition "area=auth;layer=api" link-evidence --project "$P" --author "$A"
lettuce cell transition "area=auth;layer=api" harden --project "$P" --author "$A"
lettuce cell rollup --by area --project "$P"    # per-member floor state + hardened ratio, N/A-excluded

Adding evidence does not advance the cell's state: cell evidence add records the link, and cell transition link-evidence is the separate step that moves in_progress to evidence_linked. Skipping it makes harden refuse with FW-WF-TRANSITION-NOT-ALLOWED (harden is declared only from evidence_linked and smoke), which reads like a gate failure but is not one.

harden is gated on evidence that authorises, which is a higher bar than evidence that exists. A linked task authorises only when it is done and carries a custom/grc run-case pin — a task that is merely done still refuses, with FW-WF-GATE-UNSATISFIED. Use --facilitate to record-not-enforce when the pin is genuinely not applicable.

See also

• Cells — Commands — the commands in the Cells group (cell, board, dimension).
• Coverage grid — Commands — the grid subcommands.
• Dimensions · Scopes · Packs · Why lettuce

> Not the same "graph" as Graphs — authored process. That page is about > graph-defs and run-cases — authored process enacted on the ledger. This page is about the > task dependency DAG: the plain depends-on / blocks lists on tasks. The two are unrelated > except by name.

What an edge asserts

A depends-on B means B must be complete before A can start. The edge is stored on the dependent and names its prerequisite, so edges run dependent -> prerequisite.

lettuce task create P/A --depends-on P/B          # at create time, repeatable
lettuce task set-list P/A depends-on --value P/B  # afterwards — REPLACES the whole list

task set-list replaces rather than appends: pass every value you want to keep.

What does not belong on it. The edge feeds a schedule computation, so it should carry only real work prerequisites:

• Not merge ordering. "These two branches touch the same generated file" is a fact about a branch, and it evaporates when either lands. It is not a dependency of the work.
• Not topical relatedness. "These are both about auth" is not a schedule constraint. Use --label/--component for classification, or the generic non-blocking relates-to list (lettuce task set-list P/A relates-to --value P/B) when you want an explicit see-also link between two tickets. A relatedness edge on depends-on inflates the critical path with a constraint nobody is waiting on, which is exactly why relates-to is kept OUT of the precedence graph.
• Not "A cannot finish until B". This one is the easiest to get wrong, because it is a real constraint and it feels like a prerequisite. But the edge asserts B gates starting A, and a task already in progress is by definition startable. Writing it would claim the work had not begun and would extend the critical path by a constraint nobody is waiting on to begin.

There is deliberately no relation for finish-to-finish. The edge exists to feed one schedule computation — cycles, the critical path, and which tasks are ready to start — and a finish-to-finish constraint feeds none of the three. Record it where it is true: a comment on the ticket, or the ticket's own status. Leaving it unmodelled keeps the schedule honest; modelling it here would make every reader of critical_path wrong instead.

Which end is ready to start

query graph reports roots and leaves, and the names read backwards from planning intuition:

| | definition | means | when to start it | |---|---|---|---| | leaves | no outgoing edge | depends on nothing | now — these are the ready work | | roots | no incoming edge | nothing depends on them | last — the final deliverables |

Demonstrated on a three-task chain, SHIP depends-on BUILD depends-on DESIGN:

critical_path : ["demo/D-3", "demo/D-2", "demo/D-1"]   length 3
roots         : ["demo/D-3"]    SHIP   — depends on everything, startable LAST
leaves        : ["demo/D-1"]    DESIGN — depends on nothing,    startable NOW

To answer "what should I work on next", read leaves, not roots.

What reads the edges

lettuce query graph --project P [--relation depends-on|blocks|precedence]   # whole project
lettuce task graph P/A --relation depends-on --depth 2                      # one task's neighbourhood

• query graph builds the DAG over every task in the project and reports cycles, acyclic, the critical_path (the longest chain by node count — the sequence that gates completion), roots and leaves.
• --relation precedence reads depends-on and blocks together, folding each into a single precedence direction. The two single-relation modes each see only their own list, so a cycle whose closing path alternates between them is invisible to both. The write gate refuses such a cycle (see below), so a store holds one only after an import or a direct edit; read three ways, the three tasks of that store give:

  --relation depends-on   acyclic true    edge_count 1
  --relation blocks       acyclic true    edge_count 2
  --relation precedence   acyclic FALSE   edge_count 3   cycles 1

Reach for it when a project populates both lists. depends-on and blocks remain the right answer for "what does this one relation say".

• task graph traverses outward from one task. A traversal capped by --depth sets truncated: true and marks each boundary node has_more, so an incomplete closure is never silently returned.
• Soft-archived tasks are hidden by default in both — as nodes and as edge targets — so they cannot distort roots, leaves, cycles or the critical path. --include-archived opts them back in.

blocks is a second, independent list — not the inverse

Setting depends-on does not populate anything's blocks. The two relations are parallel lists you maintain separately:

D-2  depends-on = demo/D-1     blocks = (empty)
query graph --relation blocks  ->  edge_count 0, every task both a root and a leaf

So a store with a fully populated depends-on graph answers zero for --relation blocks. Pick one relation as the project's convention and populate that one; a half-populated pair is worse than either alone, because both queries look answerable and only one is.

If a project does populate both, read it with --relation precedence. That mode is the only one that sees the two lists as one order — and it does not merge them into each other: blocks and depends-on stay separate lists that point opposite ways, which is exactly why folding them needs a mode of its own rather than an inverse.

A cycle means the store was changed outside the CLI

Ordinary writes refuse both of the states that would corrupt the analysis: a dangling edge, and an edge that would close a cycle. On the three-task chain above (D-3 depends-on D-2 depends-on D-1):

task set-list P/D-2 depends-on --value P/D-1  ->  ok: true
task set-list P/D-3 depends-on --value P/D-2  ->  ok: true
task set-list P/D-1 depends-on --value P/D-9  ->  FW-REF-MISSING-TASK   referenced task does not exist
task set-list P/D-1 depends-on --value P/D-3  ->  FW-REF-CYCLE          edge would create a cycle

(A value that is not a task reference at all, such as P/NOPE, is refused earlier, by the reference grammar: FW-NAME-TASK-ID.)

The cycle check reads the two lists together, across every project (LET-619, v0.19.0). A cycle that alternates between blocks and depends-on is refused on the write that would close it, exactly like a cycle within one relation:

task set-list P/T-1 blocks     --value P/T-2   ->  ok: true
task set-list P/T-3 depends-on --value P/T-2   ->  ok: true
task set-list P/T-3 blocks     --value P/T-1   ->  FW-REF-CYCLE   would close T-1 -> T-2 -> T-3 -> T-1

So neither a dangling edge nor a cycle of any shape can be authored through task set-list or task create. When query graph reports acyclic: false, under any --relation, that is an integrity finding, not a planning mistake: the edges arrived by import or by a direct file edit. validate --strict reports such a store at rest. Here the closing edge was written straight into the file:

validate --strict                    ->  reports FW-REF-CYCLE   task depends-on/blocks relations form a precedence cycle
query graph --relation precedence    ->  ok: true               acyclic: false, one cycle

Note that validate still answers with ok: true while data.valid is false (and exits 1): the command succeeded, the store did not. Treat it as a repair task: see lettuce doctor and lettuce repair plan.

When cycles are present the critical path is still well-defined: it is computed over the graph with the cycle back-edges removed.

See also

• Tasks and the work plane · Queries (FQL)
• Tasks — Commands · Queries — Commands
• Graphs — authored process, enacted on the ledger — the other graph

A dimension is one quality axis along which cells are graded — for example test-coverage, input-validation, or the coverage pack's lettered axes (A functional, I attack-surface, …).

Structure

• Family — dimensions are grouped into families. The coverage pack's 88 dimensions span 15 families: ten engineering families (correctness, usability, interface, security, reliability, distributed, performance, maintainability, delivery, process) plus a five-family product-lifecycle super-family (product, market, customer, growth, lifecycle).
• Applicability — each dimension is universal (always applies) or conditional (applies only when relevant to the unit). Which conditional axes a given product-type should require vs treat as N/A is a judgment you record by declaring a scope's applicable grid dims and marking the rest N/A (exclude) deliberately.
• Closed vs open — a closed dimension has a fixed member enumeration; an open dimension mints members ad-hoc as coordinates use them.

Members

A member is one enumerated value of a dimension, first-class: {slug, name, description, rank}.

• An empty name renders as the slug.
• rank 0 = unranked (sorts by slug); otherwise members sort by rank.
• dimension member add / dimension member update edit only project-declared dimensions — never pack-owned vocabulary.

Methodology — how to apply a dimension

Every dimension carries two distinct texts, and both matter:

• description says what the dimension *is* — the quality axis itself (e.g. dim D: "Writes are atomic and durable; a crash mid-write leaves a recoverable, consistent store.").
• methodology says how to apply it to a unit — the procedure an agent follows to grade a cell honestly. In the coverage pack a methodology has up to six facets. Every dimension carries at least Procedure and Hardened; the enriched axes add the middle four:
• Procedure — the concrete steps to exercise this dimension on a unit.
• Best practices — what "good" looks like; the do's and don'ts for that dimension's family (correctness / usability / security / …).
• Tools — named, current tooling that exercises this axis well.
• Current approaches — the present-day state of the art for the axis.
• Evaluation — the metric + evidence bar per member; how to score honestly.
• Hardened — the evidence bar: what a bite-proven guard must do. Across the whole pack, hardened means the same thing — a committed guard that provably bites under fault injection (green → break → RED → green); for non-code axes (process, compliance) the bar is an audit or freshness gate that fails on a missing or stale artifact. Attestation and prose never reach hardened.

> The methodology is a free-form string; the six-facet form above is the > current standard, and every bundled coverage dimension now carries it in full.

Example — coverage dim D (Data integrity / atomicity / persistence):

Procedure: exercise the write path; assert ATOMICITY (write-temp-then-atomic-
  rename or a WAL) and DURABILITY (fsync the file AND its parent dir before ack);
  inject a torn/partial write (crash mid-write, truncated temp, kill -9) and assert
  the store stays consistent + read-back returns the exact bytes. Then name the
  isolation level and prove the anomalies it forbids don't occur.
Best practices: make the ACID story EXPLICIT; writes are write-temp-then-atomic-
  rename never in-place; never ack before durable; "validated but never persisted"
  is a real bug class, so read the canonical file back and assert exact bytes.
Tools: atomic rename(2), fsync/fdatasync + directory fsync, WAL engines (SQLite
  WAL, LMDB, BoltDB); Jepsen elle for isolation; ALICE/CrashMonkey crash injection.
Current approaches: MVCC + snapshot isolation as the default; serializable via SSI;
  elle infers isolation anomalies from histories; deterministic simulation.
Evaluation: atomicity (no torn write survives a crash); durability (an fsync'd
  write survives power loss); isolation (forbidden anomalies never observed);
  multi-object atomicity (a reader never sees a partial commit).
Hardened: a committed torn/partial-write guard bites (green → break → RED → green)
  if atomicity/durability is removed; layer an isolation guard + a fsync-durability
  guard. Distinct lens vs F (F = in-process race-safety; D = the store's contract).

Read a dimension's methodology before grading any of its cells: lettuce dimension show <slug> --project <p> (one axis, full text) or lettuce dimension list --project <p> --format json (the whole effective set) surfaces it. The methodology catalog is the orientation board — the six-facet contract, a family-by-family map of all 88 dimensions, and fully worked exemplars. The methodology guidance is what distinguishes a smoke (exercised) grade from a hardened (bite-proven) one.

> Rule: a dimension without a methodology is incomplete. A quality axis you > cannot tell an agent how to grade is not yet a usable dimension — the > description/methodology pair is mandatory, not decorative.

Effective dimensions = pack ⊕ project layer

A project's effective dimension set is the active pack's dimensions plus an additive project runtime layer declared with dimension declare. The project layer is strictly additive: it can add axes and members but never shadows or overrides pack vocabulary.

Renaming a project dimension

A project-declared dimension's slug can be changed with dimension rename OLD NEW --project P. It is a whole-store structural migration, not a directory move, because the slug is three things at once: a path segment (projects/P/dimensions/<slug>/), the leading component of a qualified reference (P/dimensions/<slug>, the target of every dimension event), and a key inside every cell coordinate. Since a coordinate is the cell's identity, changing the key changes each affected cell's address — so the rename moves each cell directory to its new coordinate hash, carrying the whole cell across (state, note, revision, its own events ledger, and its evidence links with their asserted_at/asserted_rev provenance). The dimension keeps its family, closed-ness, members and its own ledger.

It is applied atomically: on any failure the store is left byte-unchanged, and it refuses rather than shipping a partial rename when a reference cannot be rewritten faithfully — one folded into a content-addressed identity (a graph-run-case advance event, a carrier directory), a stored saved query naming the dimension (the FQL cells source projects scope/unit/dim/group/ kind as fixed columns), or a move off/onto a reserved coordinate axis that the project's declared grid or DoD keys off. A pack-bundled dimension is compiled into the binary and is not renameable.

Coordinates

A cell lives at a coordinate — dim=member;dim=member. Pairs are sorted by dimension, duplicates are rejected, and every slug is validated against the effective vocabulary. An untouched coordinate is not stored; it reads as the pack default with stored=false.

See also

• Methodology catalog — the orientation board: the six-facet contract, all 88 dimensions by family, and worked exemplars.
• Dimensions — Commands (the dimension subcommands live in the Cells group)
• Cells · Packs

> Not the task dependency graph. depends-on/blocks between tasks — and the > cycles/critical-path analysis query graph runs over them — are > Dependencies. This page is about graph-defs and run-cases: > authored process enacted on the ledger. The two share a name and nothing else.

Most of lettuce tracks what is true: a cell asserts a state, a task moves through workflow, evidence hardens a claim. Graphs track how work is meant to proceed — and then record what actually happened when it did.

Two objects, deliberately separate:

| object | what it is | mutability | |---|---|---| | graph-def | the authored shape of a process — nodes wired by edges, from a start node | versioned data, revised deliberately | | graph-run-case | one enactment of a def on the real ledger | event-sourced; state == f(events) |

Reach for a graph when a process is repeatable, multi-step, and worth auditing — when you want the same shape run many times and each run to leave falsifiable evidence. For a single piece of work, a task is the right unit; for legal states and transitions of that work, see Workflow; for what is true about an area, see Cells.

Definitions are sound by construction

A graph-def is data at projects/<p>/graph-defs/<slug>/. Its spec body is stored append-only-versioned, the same way a task body is.

Creation folds in the soundness gate: a dangling edge, an unreachable node, a missing start, or an uncapped cycle is refused and never stored. So "stored" and "sound" are the same statement — you never have to ask whether a def in the store is coherent. Linting is separate and advisory: it reports design smells as warnings, never fatal.

Composition: a def can use another def

A node may be a subgraph that inlines another def by name and binds its open ports. Compilation resolves the transitive closure, inlines every referenced def, and hashes the whole expansion. Two consequences worth holding onto:

• editing a shared pattern moves the effective-hash of every parent that uses it;
• a composition cycle is refused, as is a reference to a def that does not exist.

This is what makes patterns reusable without making them silently divergent.

Enactment: what a run-case records

Opening a run-case positions it at the start node and mints an id. From there it is advanced across edges and finally resolved. Because state is derived from events, the ledger — not a scalar someone wrote — is the authority on where a run got to.

Carriers are the data that moves along edges: content-addressed, write-once, stored at projects/<p>/carriers/. Write-once is the point — a run's evidence cannot be quietly restated after the fact.

Two terminal dispositions, one terminal event. A run that was walked to the end is closed, with an optional --outcome. A run that was opened and never walked to the end is abandoned, and there --reason is required — an abandonment records no work, so the reason is the whole of what the ledger can say. Both write the same case-closed event through the same writer: one terminal, not two. A run that already has a disposition refuses a second one, because two dispositions is a fork in the record. Abandoning is never a delete — the run stays listed and inspectable, and it is excluded from the conformance denominator rather than judged for a walk that never happened.

The disposition is projected onto every read surface, so an abandoned run never has to be mistaken for a completed one:

• show carries disposition beside state, and the required --reason is readable as outcome — the same field a closed run uses for --outcome.
• list carries disposition per case, and counts them: total, open, abandoned.
• viz writes the disposition into the diagram bytes as a %% comment, not just into the envelope. That placement is deliberate: viz > graph.mmd is the normal way the command is used, and an envelope-only field would vanish exactly there. An abandoned walk otherwise draws the same picture as a completed one.

conform remains the other half of the answer — it reports excluded: true for an abandoned case rather than judging a walk that never happened.

The reproducibility pin, and what it does not do. When the named def has a stored effective-hash, opening a run-case copies that hash verbatim onto the open event. Revising the def later moves the def's hash without re-pointing this run's evidence, so a completed run stays falsifiable rather than retroactively re-interpreted.

What the pin does not do is constrain the walk as it happens. The runtime is deliberately graph-def-free: advance reads no spec, so --to and --edge accept any string. A run-case can traverse an edge its def never declared, name a node absent from it, and still close with validate --strict reporting a perfectly clean store. That is by design, not an oversight — but it means the pin names the topology a run claims to have followed rather than proving it followed one.

Conformance replay is what makes the pin binding. It resolves the pinned hash back to the spec version that minted it and replays the recorded walk against that text, reporting an undeclared edge, an unknown node, or a join fired below its declared quorum. Judging against the pinned version rather than the latest is the whole point: revising a def cannot retroactively change the verdict on a run that finished before the revision.

This matters because every other check over a run-case re-derives its verdict from parameters the run itself recorded — the join re-folds the quorum the caller wrote. Each is therefore a fixed point: internally honest, and structurally unable to notice that the recorded number is not the declared one. Conformance is the read-time counterpart that can. It is a report, not a refusal — a non-conforming walk is evidence to read, not corruption to block — and it exits non-zero so a script can gate on it without parsing JSON.

Runtime patterns

Structured parallelism and iteration are authored in the def (and folded into its hash) but enacted in the run-case:

• fork / join — a fork opens concurrent branches; a K-of-M join fires only once quorum actually arrives, and refuses otherwise;
• loops — a capped back-edge exits only when its oracle is satisfied (converged, drained, a minimum count, a circuit-breaker), and refuses if not;
• routers — a router picks its out-edge from the run-case's own recorded evidence (carriers, wave outcomes, produced effects), evaluated through a small deterministic guard grammar. Never from the caller's assertion.

Each of these is guarded by an explicit refusal rather than a best-effort guess. That is the same stance as the rest of lettuce: a gate that cannot be satisfied is reported, not papered over.

Where to go next

• Graph Authoring — Commands — creating, revising, compiling, linting and visualising defs, and the catalog of shared patterns.
• Graph Run-Cases — Commands — opening, advancing, closing or abandoning run-cases, replaying conformance, and producing carriers.
• Cells — what a run-case's effects can harden.
• Store — how event-sourced state and derived scalars stay coherent.

This is the orientation board for the coverage pack. Before you grade any cell on a dimension, read that dimension's methodology: it tells you everything you could and should do to consider the dimension properly, and the evidence-quality bar a hardened grade demands.

The coverage pack ships 88 dimensions across 15 families, each carrying a methodology. This page teaches the methodology contract, maps every dimension to its family, and shows three fully-worked exemplars. It deliberately does not reproduce all 88 methodologies — that content lives in one always-current place:

lettuce dimension list --project P --format json          # all 88 dims + full methodology
lettuce dimension list --project P --format json \
  | jq '.data.dimensions[] | select(.slug=="AL")'         # one dimension, full text

> The binary is authoritative. coverage.yaml is embedded in the binary, so the > command above always reflects the exact methodology the current release grades > against — the exemplars below are a readable snapshot, not the source of truth.

The methodology contract — how to read a dimension

Every dimension carries two distinct texts, and both matter:

• description — what the axis is (the quality property itself).
• methodology — how to apply it: the procedure an agent follows to grade a cell honestly, and the bar each grade must clear.

A methodology has up to six facets. Every dimension carries at least Procedure and the Hardened evidence bar; the enriched axes add the middle four:

| Facet | What it answers | |---|---| | Procedure | The concrete steps to exercise this dimension on a unit. | | Best practices | What "good" looks like — the do's and don'ts for the family. | | Tools | Named, current tooling that does this well. | | Current approaches | The 2025–26 state of the art for this axis. | | Evaluation | The metric + evidence bar per member; how to score honestly. | | Hardened | The evidence bar for hardened — a committed guard that provably bites under fault injection (green → break → RED → green), or, for non-code axes, an audit/freshness gate that fails on a missing or stale artifact. Attestation and prose never reach hardened. |

> Every dimension now carries the full six-facet form (Procedure · Best practices · > Tools · Current approaches · Evaluation · Hardened). Either way, a dimension without > a methodology is incomplete — you cannot grade what you cannot be told how to > grade.

The evidence bar, stated plainly. hardened is never earned by "we looked at it and it seemed fine." For a code axis it demands a committed guard that bites — remove the safeguard and the guard goes RED. For a non-code axis (process, compliance, agentic-loop) it demands an audit or freshness gate that fails on a missing, unsigned, or expired artifact. The Hardened facet of each dimension spells out exactly what its bar is.

The grading ladder (coverage's state machine): untested → gap | smoke → hardened, via the exercise, flag-gap, exercise-gap, and harden transitions. harden is gated by guard-bite — at least one evidence link to a done task that carries custom/grc (the pin of its verified close walk) — the only path to hardened. exclude marks a dimension structurally N/A (it leaves the denominator). See Cells — the coverage model for the full grade/state model.

Families — the navigation map

All 88 dimensions across 15 families. Read a dimension's full methodology with the jq snippet above (slugs are upper-case, e.g. AL).

| Family | Dimensions | |---|---| | correctness (6) | A functional correctness · C spec-impl fidelity · N domain-model completeness · O compat/versioning/migration · Q release-compat contract · U internal consistency | | usability (11) | B UX/DX · S self-documentation · T error-handling & messaging · M docs & examples · AY accessibility (a11y) · BI i18n/l10n · VD visual & product design · AX agent experience · KB knowledge-base & self-doc quality · WL white-label & theming · BC browser/client compatibility | | interface (6) | H HTTP/API surface · J import/export round-trip · BX agent-readiness · CB multichannel parity · AP agent-protocol interoperability · DP data portability & anti-lock-in | | security (9) | I attack surface · V privacy · AO rate-limiting/abuse · AZ bounded resources · BD auditability · RT red teaming · PT purple teaming · TM threat modeling · RC regulatory compliance & enforcement | | reliability (11) | BZ temporal-correctness · D data integrity/atomicity · E resilience/recovery · F concurrency/race-safety · FP cross-process concurrency & lock-safety · EL service liveness & crash-isolation · AM idempotency · CC resource-cleanup · AN backup/DR · AT determinism · OP operations & incident response | | distributed (2) | G multi-node/sync · CA storage-backend equivalence | | performance (4) | L performance/efficiency · P observability · SC scalability patterns · DT distributed tracing & trace ownership | | maintainability (6) | K code-quality · AA maintainability · AB testability · R configurability · BL architecture · CS code smells & anti-patterns | | delivery (10) | AC licensing · AR supply-chain/SBOM · AS deploy/release · BM CI-CD health · BN packaging · BY stack maturity · BP cross-platform portability · LG legal, IP & terms · CN cloud-native / kubernetes deployment · RG reproducible generation & asset provenance | | process (8) | TD TDD discipline · GQ quality-gate quality · TK tracking & board discipline · QA QA procedure (full) · RV adversarial/peer review · AL agentic development-loop quality · PM engineering-process maturity & artifacts · RQ research & inquiry quality | | product (3) | PA product analytics & north-star instrumentation · XP experimentation & A/B testing · PD product discovery & prioritization · _(product-lifecycle super-family — growing)_ | | growth (2) | PR pricing & packaging · MN revenue, billing & unit economics | | customer (4) | ON onboarding & activation · SU customer support & service · CX success, retention & churn · FB feedback & voice-of-customer | | market (4) | PO positioning & messaging · DG demand generation & campaigns · SE content, SEO & GEO/AEO discoverability · IR investor & stakeholder communications | | lifecycle (2) | FO cloud cost & FinOps efficiency · SN deprecation, EOL & sunset |

Worked exemplars

Three dimensions rendered in full — one from reliability (a code axis whose bar is a biting guard), one from security (a mixed code-and-artifact axis), and one from process (an axis whose bar is deliberately mixed-gateability). This is the pattern every dimension follows; pull any other with the jq snippet above. In the Phase-2 generated reference/coverage-catalog.md, every dimension renders like these.

---

D — Data integrity / atomicity / persistence

Family: reliability · Applicability: universal

What it is. Writes are atomic and durable (a crash mid-write leaves a recoverable, consistent store) AND the store's transaction/isolation contract is explicit and honest — the ACID story is named and proven, not assumed.

Procedure. Exercise the write path; assert ATOMICITY (all-or-nothing — write-temp-then-atomic-rename, or a WAL/journal) and DURABILITY (fsync the file AND its parent directory before ack — an un-fsync'd rename can vanish on power loss); inject a torn/partial write (crash mid-write, truncated temp, kill -9 between write and rename) and assert the store stays consistent + read-back returns the exact bytes. Then the TRANSACTION depth: name the isolation level the store offers (read-committed / snapshot / serializable) and prove the anomalies it forbids do not occur — dirty read, non-repeatable read, phantom, and write-skew (snapshot isolation still permits write-skew; only serializable forbids it); if multi-object/multi-file atomicity is claimed, prove a concurrent reader never observes a half-applied multi-key commit (it sees pre- or post-state, never mid).

Best practices. Make the ACID story EXPLICIT — Atomicity (temp+rename/WAL, single commit point), Consistency (invariants hold across the commit), Isolation (name the level; document that snapshot permits write-skew), Durability (fsync file

• parent dir; group-commit for throughput); writes are

write-temp-then-atomic-rename never in-place; never ack before durable; "validated but never persisted" is a real bug class, so read the canonical file back and assert exact bytes (no more, no less — a single-version test misses append-only latest-version bugs); never expose a partially-applied multi-key mutation; treat isolation level as a documented contract. Don't: fsync the file but not its dir, rely on OS buffering for durability, or claim serializable while shipping snapshot.

Tools. atomic rename(2) (same filesystem), fsync/fdatasync + directory fsync, WAL/journal engines (SQLite WAL, LMDB, BoltDB single-writer MVCC); isolation reasoning ANSI SQL levels, snapshot-isolation/MVCC, Jepsen elle (cycle-detection isolation checker over observed histories); crash injection ALICE/CrashMonkey-style FS fault injection, kill -9 harnesses, power-cut simulation, deterministic simulation (FoundationDB/TigerBeetle VOPR).

Current approaches. MVCC + snapshot isolation is the default store concurrency model; serializable via SSI (PostgreSQL) or lock-based (CockroachDB/TiDB/YugabyteDB proved true serializability via Jepsen); elle infers isolation anomalies from histories — the modern way to PROVE an isolation claim rather than assert it; deterministic simulation crash-tests the durability path exhaustively; group-commit + fsync batching for durable throughput.

Evaluation. atomicity (no torn write survives a mid-write crash); durability (an fsync'd write survives power loss — verified with a crash/barrier harness); isolation (the claimed level's forbidden anomalies never observed via an elle-style history check); multi-object atomicity (a reader never sees a partial commit). Evidence = a crash-injection log + an isolation-history check.

Hardened (evidence bar). KEEP the committed torn/partial-write guard — it bites (green → break → RED → green) if atomicity/durability is removed and the store is left inconsistent. LAYER: an isolation guard that bites when a concurrent reader observes a half-applied multi-key commit (interleave a multi-file mutation with a read; assert the read sees pre- or post-state, never mid), and a durability guard asserting the write is fsync-durable (remove the dir-fsync → a crash harness loses the rename → red). Distinct lens vs F (F = in-process race-safety of the mechanism; D = the atomicity/durability/isolation CONTRACT of the store).

---

RC — Regulatory compliance & enforcement

Family: security · Applicability: conditional

What it is. The product is graded against a regulatory or platform-policy REGIME (the member = hipaa/gdpr/soc2/pci-dss/iso27001/app-store-review/play-store-policy/…) control-by-control with linked evidence, and enforcement = a committed control-check that BITES when a required safeguard is absent, misconfigured, or removed.

Procedure. Pick the regime (member: hipaa/gdpr/soc2/pci-dss/iso27001/nist-800-53/fedramp/ccpa, OR a PLATFORM-POLICY gatekeeper regime — apple-app-store-review / google-play-policy, whose "controls" are the store guidelines + content-rating + data-safety/privacy-nutrition-label declarations and whose "audit" is the store's pre-publish review that can reject the artifact) and scope the compliance boundary (in-scope systems/data — PCI Cardholder Data Environment, HIPAA ePHI systems, GDPR personal-data systems) as a versioned artifact (data-flow diagram, asset inventory, network map); enumerate the regime's applicable controls (PCI's 12 requirements, ISO 27001:2022 Annex A's 93 controls, HIPAA Security Rule 164.308/.310/.312 safeguards, SOC 2 Trust Services Criteria, NIST 800-53 families) marking each applicable or N/A with WRITTEN justification; map each control → implemented safeguard + dated evidence (the control-to-evidence traceability matrix); record every gap (owner, severity, remediation date) in a gap register; remediate; wire an automated control-check that FAILS when a technical safeguard is absent/drifts, and an artifact-freshness check that fails when a signed process-control artifact is missing or past its review-by date; run continuously in CI + scheduled scans (audit-ready always, not point-in-time).

Best practices. compliance-as-code (controls as executable policy in git, not GRC-spreadsheet prose — a control's truth is its passing check, reviewable in a PR); control-to-evidence traceability (dated reproducible evidence, not "the policy says X"); never check the box without proof; continuous over point-in-time; scope discipline (tokenize/segment/pseudonymize out of scope — the cheapest control is the one you removed from scope); cross-framework mapping (one safeguard e.g. encryption-at-rest satisfies HIPAA 164.312, PCI Req 3, ISO A.8.24, SOC 2 CC6.1, GDPR Art 32 — evidence once, reuse everywhere); separation of duty on evidence (the implementer is not the sole signer); least-privilege + immutability on the audit/evidence store itself (a mutable audit trail defeats the control).

Tools. control catalog OSCAL (NIST machine-readable catalog/profile/SSP/POA&M) + IBM Trestle; policy-as-code OPA/Rego + Conftest, Checkov (1000+ IaC policies mapped to CIS/NIST/PCI/SOC2/HIPAA), Cloud Custodian (CNCF, auto-remediation), Prowler (multi-cloud, built-in HIPAA/PCI/SOC2/GDPR/FedRAMP frameworks), Trivy/Kubescape/Terrascan/kube-bench; continuous-compliance platforms Vanta/Drata/Secureframe/Sprinto (+ Scytale/Anecdotes); cloud-native AWS Config conformance packs + Security Hub, Azure Policy + Defender for Cloud, GCP Security Command Center; evidence pipeline SIEM/CloudTrail, Vault, IdP logs (Okta/Entra) for access + MFA evidence.

Current approaches. continuous compliance / compliance-as-code is dominant (controls are code, evidence auto-collected on a schedule, drift alerts near-real-time — "audit-ready always" replaces the annual scramble); cross-framework control mapping (implement+evidence a safeguard once, inherit across SOC2/ISO/HIPAA/PCI/GDPR — so "add HIPAA" onto an existing SOC 2 program is incremental, not a restart); machine-readable regulation (FedRAMP 20x + RFC-0024, Jan 2026, mandates OSCAL packages + Key Security Indicators with continuous validation — tooling lag is real but the direction is set); automated evidence collection (read-only integrations snapshot cloud config/IdP-MFA/vuln results on a cadence); shift-left compliance (IaC scanners gate the PR so a non-compliant resource never reaches production).

Evaluation. control coverage (% of the regime's APPLICABLE controls with an implemented + fresh-evidenced safeguard; HIPAA/PCI demand ~100% of applicable, ISO/SOC 2 tolerate documented risk-accepted exceptions justified in the Statement of Applicability / management assertion); evidence freshness (each artifact timestamped + max-age — technical-check evidence within the scan window ~24h, process artifacts within their review cycle: BAA current, DPIA annual, pentest ≤12mo, access review ≤quarterly; stale evidence = uncovered); gap-register health (open gaps + severity + owner + date; open criticals block hardened); scope correctness (boundary documented, asset inventory matches reality, N/A justifications hold). Evidence QUALITY auditors expect: reproducible, independent (not self-attestation), complete (whole population not a hand-picked sample), timestamped + attributable, tamper-evident. SOC 2 Type I (design at a point in time) vs Type II (operating effectiveness over a 3–12mo window) — Type II needs evidence the control operated CONTINUOUSLY, exactly what a biting automated check produces.

Hardened (evidence bar). A regime cell is hardened only when EVERY applicable control is enforced by either a biting automated check OR a fresh signed artifact, the two classes are paired, and the gap register is empty. Technical controls = a committed check that fails when the safeguard is absent/drifted: encryption at rest/in transit fails on any in-scope datastore storing PHI/PAN/personal-data with encryption off (flip a test bucket insecure → red); MFA on all privileged/in-scope access; audit logging enabled + retained + immutable; config drift from baseline; the data-subject-rights erasure/portability/access path ACTUALLY EXECUTES (a technical control weak programs wrongly attest — make it bite); vuln/patch SLA. Process/attestation controls = a signed, dated, non-expired artifact graded by a freshness check: BAA per PHI-touching vendor; DPIA/RoPA; ISO Statement of Applicability + certificate; SOC 2 Type II report; PCI ROC/SAQ + pentest; FedRAMP SSP/POA&M/3PAO. Enforcement principle: wherever a control CAN be technically verified it MUST be a biting check — attestation is not acceptable for what a machine can prove ("we encrypt PHI" must be a failing test on unencrypted PHI, never a signed sentence); pair a signed report with the biting check of its underlying technical control, either alone is insufficient.

---

AL — Agentic development-loop quality

Family: process · Applicability: conditional

What it is. When an AI agent (or fleet) is doing the development, the build→verify→improve→reflect LOOP itself is a graded engineered system — autonomous, resilient, observable, convergent, cost-bounded — proven by instrumented evidence, not agent vibes. Member = a loop property (autonomy / resilience / provenance / observability / stability / scalability / effectiveness / speed-quality / overhead / self-reflection / self-tuning).

Procedure. Name the loop under test (agent/scaffold — Claude Code, OpenHands, SWE-agent, Cursor, a custom harness; repo/scope; the gates it drives) and its unit of progress (a landed PR, closed ticket, hardened cell, passed task); INSTRUMENT before judging (OpenTelemetry GenAI / OpenInference spans for every model call, tool call, reasoning step, token+cost — you cannot grade a loop you cannot see); then exercise each loop PROPERTY with a deliberate probe not a happy-path watch: autonomy (measure human-interventions-per-unit over a real unattended window → SAE-style L0–L5), resilience (INJECT a mid-loop failure — kill a step, corrupt a tool result — and observe self-recovery without human rescue), stability (run N≥5 iterations, watch for green→red oscillation vs monotone convergence), scalability (1 then k parallel agents on isolated worktrees, measure throughput + collisions), effectiveness (resolve rate on SWE-bench Verified/-Live/Terminal-Bench or an internal set), speed-quality (iterations/wall-clock against a FIXED quality floor), overhead (cost-per-completed-task = attempt-cost / solve-rate), provenance (sample decisions from the trace, each must link a rationale+evidence), self-reflection + self-tuning (the loop critiques its own runs and adjusts from a scored record, not folklore); score each member on evidence quality; aggregate + name the weakest property + its next probe.

Best practices. instrument first, judge second (an un-traced loop is capped at 'covered' — 'we watched it, it seemed fine' is the vibe score this dim kills); autonomy is a dial not a switch (state the OBSERVED SAE level + intervention rate; most 2025-26 production loops are L2-L3, ceiling L3 conditional; never claim 'fully autonomous' without an unattended trace); converge not churn (every iteration reduces distance-to-done and never regresses an already-green gate — green→red→green oscillation is a first-class loop defect); every decision carries its receipt (rationale + the failing test/file/prior result that drove it); recover without a human (retry-safe/idempotent steps + checkpoints; distinguish transient infra faults — retry/circuit-break — from semantic faults — Specification Drift/Reasoning/Tool-Call — which blind retry just burns tokens on); parallelize with isolation, merge with judgment (worktrees give filesystem isolation only; decomposition/semantic-conflict/ merge-selection are still yours; adding agents must add LANDED output); govern speed-quality explicitly (a velocity floor the gate suite may not breach); budget on cost-per-completed-task not raw tokens; benchmark against a contamination-resistant set (SWE-bench-Live ~19% vs Verified 60%+ exposes overfitting).

Tools. eval/effectiveness SWE-bench + SWE-bench Verified (500-task human-validated), SWE-bench-Live (anti-contamination), Terminal-Bench + Long-Horizon-Terminal-Bench, Holistic Agent Leaderboard (HAL)/Live-SWE-agent (cost-annotated); scaffolds SWE-agent, AutoCodeRover, OpenHands, Devin, Claude Code (--worktree), Cursor 2.0 (multi-agent), Aider, ccswarm; observability/AgentOps LangSmith, Langfuse (OSS), AgentOps, Arize Phoenix (OpenInference), W&B Weave, Traceloop/OpenLLMetry over the OpenTelemetry GenAI semantic conventions (the portable substrate); resilience/durable-execution Restate, Temporal (checkpoint+resume, exactly-once), circuit-breaker/retry libs, MAPE-K loops; parallelism git worktrees + lock-safety (ties to FP); cost provider token/usage APIs + cost-per-resolved-task.

Current approaches. the instrumented agentic SDLC (every run traced with OTel GenAI/OpenInference; the decision graph — not a re-run — is the primary debugging artifact; observability consolidated on LangSmith/Langfuse/AgentOps/Phoenix/Weave); autonomy as a measured SAE-style dial (L2-L3 consensus, L3 ceiling); self-healing loops (failure-classified repair — circuit-break transient, corrective-feedback/rollback semantic — over durable-execution state so a recovered agent CONTINUES not restarts); contamination-aware effectiveness (Live/fresh sets, cost reported alongside score); parallel-agent fleets on worktrees (Cursor up to 8 concurrent) with the honest caveat that worktrees solve low-level isolation only; governed speed-with-a-floor as the loop-level 'keep-green'.

Evaluation. each member has a distinct metric + evidence bar — evidence must be reproducible (re-run yields the same class of outcome), instrumented (from the trace/harness, not a screenshot/prose), windowed (over a real run of N iterations or a benchmark subset, not one cherry-picked pass), and where gate-able biting (fails when the property is broken). autonomy = interventions/unit threshold audited off an unattended trace; resilience = self-recovery rate from injected failures; observability = span-coverage %; stability = green→red regressions across N runs + convergence trend; scalability = output(k)/(k*output(1)) + collision count; effectiveness = resolve rate vs a floor; speed-quality = iterations/wall-clock with the full floor still green; overhead = cost-per-completed-task budget; provenance = decision-linkage coverage; self-reflection/self-tuning = a scored eval record showing runs are critiqued + params evolve from measured winners. A single successful demo run is 'covered', never 'hardened'.

Hardened (evidence bar). deliberately mixed-gateability — its honesty is being explicit about which members bite via a committed check, which are metric-threshold-gated, and which are audit-graded. GATE-ABLE (a committed check that BITES): resilience (fault-injection test — SIGKILL a step / corrupt a tool response — asserts self-recovery; red when the loop wedges or restarts from scratch), stability (green-stays-green repeated-run harness over N≥5; red on any previously-green gate regressing), effectiveness (benchmark-score-floor CI gate; red when a loop change drops resolve rate below floor), overhead (cost-per-completed-task budget gate — the least-fakeable member, straight off the token meter), speed-quality ('faster AND floor-still-green'; red when speed came from skipping a gate), scalability (scaling-efficiency threshold + zero-cross-agent-collision assertion; red when adding agents adds no landed output or collides). METRIC-THRESHOLD-GATED (a number vs a bar, trace-audited): autonomy (interventions/unit ≤ bar for the claimed SAE level), observability (required span kinds present; red if instrumentation is dropped). AUDIT-GRADED (a review that fails on a missing artifact): provenance + self-reflection/self-tuning (fails when a sampled decision lacks a linked rationale+evidence, or a prompt/param change ships with no eval record). Cross-cutting rule: no member exceeds 'covered' from a demo or prose claim — every claim about the loop is a check that bites, a number against a bar, or an audit that fails on a missing receipt. That is precisely how this dim avoids collapsing into an 'agent vibe' score.

---

See also

• Dimensions and members — the concept: what a dimension / methodology / member is.
• Cells — the coverage model — the grade ladder, gates, and evidence model this catalog grades against.
• The shipped convention — coverage as data — how coverage is bundled as the default convention, and how you inspect and tune it.
• Project setup playbook — choosing dimensions and grading cells against their methodology.
• lettuce dimension list --project P --format json — the authoritative live read of all 88 methodologies.

Milestones

A milestone groups work toward an outcome and advances through stages — a hypothesis ladder you progress as evidence accrues.

lettuce milestone create <slug> --project P --author A --title "..."
lettuce milestone list --project P
lettuce milestone show <slug> --project P
lettuce milestone set-stage <slug> --stage <s> --project P --author A   # advance the ladder
lettuce milestone close <slug> --project P --author A

Milestones live on the Work plane alongside tasks; they organize why work is being done, while tasks are the what.

Definition of Done (DoD)

A Definition of Done declares the grade floor a project (or scope) must reach on the coverage plane — the objective bar that separates "in progress" from "done".

lettuce dod set   --project P --author A ...   # declare the grade floor
lettuce dod show  --project P                  # inspect the current DoD
lettuce dod clear --project P --author A       # remove it

Once a DoD is declared, board next prints a leading DoD: … verdict line — the honest, computed answer to "are we done yet?" A DoD turns "done" from an assertion into a measurement: the floor is met only when the cells actually grade at or above it (with excluded cells leaving the denominator).

What the floor is made of

dod set writes up to three coverage floors, checked as a strict per-scope AND-gate over the applicable (non-excluded) cells — a scope is met only when every such cell clears every declared floor, reported as a k/n count, never a blended percentage:

• --grade STATE (required on first declaration) — the minimum pack state a cell must reach to count (e.g. hardened).
• --depth N (optional) — the minimum confirmation depth (FRESH-2): how many distinct store revisions independently confirmed the grade.
• --recency fresh|aging (optional) — the minimum freshness bucket (FRESH-3): fresh (must be fresh) or aging (fresh-or-aging, never stale). A cell whose freshness is presumed (no revision anchor) counts as unknown — unmet until re-affirmed. See freshness and depth for how both are computed.

--scope S sets a per-scope override of any floor (an unset field inherits the project default). Setting a floor never moves the hardened ratio: a scope can read 100% hardened yet DoD-unmet because its proof is stale or shallow.

Beyond the coverage floors, the overall verdict layers two auto-derived outer gates you never set by hand — every committed milestone reached and zero non-terminal tickets — so a project can clear every coverage floor and still read not done. Inspect all of them via dod show / board export.

Organizing a project

A typical project shape:

1. Declare the working model — every project runs the shipped coverage convention by default; optionally add project dimensions (dimension declare) or tune the ladder with the defaults layer. 2. Declare the bar — dod set a grade floor (per project and/or per scope). 3. Frame the outcomes — create milestones with stages. 4. Do the work — tasks claimed with leases, evidenced by runs/artifacts, closing cells. 5. Steer by the board — board next weakest-first until the DoD verdict is met.

See also

• Registries & Workflow — Commands (milestone subcommands)
• Definition of Done — Commands (dod subcommands)
• Cells · Agentic cycles

lettuce ships one working convention, and it is expressed as data, not code: the set of states, transitions, gates, dimensions, and families a project grades against. That convention is coverage, and every project runs it by default — a fresh project is already on coverage with nothing to enable.

This is the mechanism-vs-convention split at the heart of lettuce: the engine is pure mechanism (it owns the containers for meaning and method), and the convention supplies the meaning (which states exist, which transitions are legal, which gates authorize them, which quality axes to grade). The convention lives as data in the binary, so the engine and the on-disk store format never have to know what any particular state or dimension means.

You do not swap the convention at the user surface. You inspect it (read what coverage declares for your project) and tune it per project with an additive defaults layer. The internal envelope still names the active convention on some read surfaces — e.g. dimension list and cell show carry a pack: coverage field — which is the convention's internal identifier, not a command you run.

The default: coverage

Coverage is a 88-dimension / 15-family quality taxonomy (the families run from correctness and security through market and lifecycle). Every coordinate you have not yet worked reads as the sparse default untested; you record real progress by transitioning cells along coverage's ladder.

The ladder (each state carries a one-letter board glyph):

| State | Glyph | Meaning | |---|---|---| | untested | U | the default — never worked | | planned | N | scheduled, not started | | in_progress | I | actively being worked | | gap | G | worked and found deficient (needs a reason) | | evidence_linked | E | progress backed by linked evidence | | smoke | S | exercised end-to-end | | hardened | H | done* — reached only through a gate that provably bites | | blocked | B | flagged: work stalled (needs a reason) | | regressed | R | flagged: a hardened cell that broke | | excluded | X | N/A for this scope (needs a reason) | | waived | W | deliberately not pursued (needs a reason) |

* = the default a fresh coordinate reads as. hardened is the only done state and the only one behind a gate: the guard-bite gate requires a committed check that provably goes green → break → RED → green under fault injection — strictly stronger than "the tests pass". The transition actions that move a cell are plan, start, exercise, flag-gap, exercise-gap, link-evidence, harden, block, unblock, waive, exclude, regress, and reopen; an action with no legal transition from a cell's current state is refused.

Inspecting the convention

Coverage is read-only data you can query per project (every read needs a store root — an explicit --root, else the nearest .lettuce directory found by walking up from the working directory, else the command refuses — and --project):

lettuce defaults show    --project P            # the effective LADDER — states/transitions/gates, each source-tagged + hidden states
lettuce dimension list   --project P            # the project's effective dimensions (source-tagged)
lettuce dimension show A --project P            # one dimension by slug, with its full methodology
lettuce dod show         --project P            # the Definition-of-Done floor + current verdict
lettuce grid show        --project P            # the declared coverage grid + denominator
lettuce board render     --project P            # the whole board as a self-contained HTML page

Each read answers a different question: defaults show = the ladder (which states, transitions, and gates the project grades against); dimension list = the axes; dod show = the Definition-of-Done floor. defaults show resolves a project's effective ladder — the bundled convention ⊕ the project's tweak layer — and tags every element with a source of default or project, so it is the read complement to the defaults tweak commands: it shows exactly what a tweak changed, base states the project has hidden (dropped from the effective view, listed under a hidden section), and where the grading-at-entry default landed. A fresh project (no tweak) resolves byte-identically to the shipped convention — every element reads source=default; after a tweak, authored states/transitions/gates read source=project and any hidden base state drops out of the ladder and appears under hidden.

dimension list reports the effective dimensions — coverage's declared axes plus any additive per-project runtime dimensions — each tagged with its source. A dimension's slug is its coverage letter (A, B, H, …); dimension show prints that axis's full procedure, best-practices, tooling, and evidence bar.

Tuning the convention (per project)

When one project needs coverage with a small adjustment, you do not author a new convention — you record an additive per-project tweak layer over the ladder / gates / DoD. A project that authors no tweak resolves byte-identically to the shipped convention; a tweak is stored under projects/<p>/… and merged at resolve time, so it never edits the bundled convention.

The defaults command family authors that layer (every subcommand is a mutation — pass --project and --author):

# additive working state (done/excluded are structural and refused)
lettuce defaults state declare triaging --category in-progress --letter T --rank 15 --project P --author A
lettuce defaults state set-default triaging --project P --author A   # move the grading-at-entry default
lettuce defaults state hide blocked        --project P --author A    # subtractive: hide a base state + its edges

# additive workflow edge (--from/--to must resolve; --gate optional, must resolve —
# but REQUIRED when --to is the done state: only a gate promotes to done)
lettuce defaults transition declare expedite --from untested --to gap --project P --author A
lettuce defaults transition declare fast-harden --from smoke --to hardened --gate guard-bite --project P --author A

# additive guard (--check-kind must be a shipped evaluator, e.g. guard-bite, consistency)
lettuce defaults gate declare peer-review --check-kind consistency --description 'two approvals' --project P --author A

# clear the tweak layer back to the shipped convention (per-scope: ladder | dod | dimensions)
lettuce defaults reset --only ladder --project P --author A

Two safety rules keep the layer honest:

1. Additive-only + validate-on-write. A tweak that would break the ladder's honesty invariants — a transition to an undeclared state, a gate naming an unknown check-kind, a set-default that would leave the ladder without exactly one default, or a state declare whose slug shadows an existing state (including a base state this project has hidden — re-declaring it would create an invisible phantom) — is refused with nothing written (exit 1, FW-CMD-USAGE). Every refusal happens before any write. There is no unhide command; to bring a hidden base state back, clear the overlay with defaults reset --only ladder. 2. A reset can't strand work. Per-scope orphan guards refuse a reset that would leave cells holding a state or dimension it removes (reassign or clear those cells first); a clean no-op reset still succeeds. 3. Only a gate promotes to done. A transition whose --to is the done-category state (hardened) must carry a --gate; an ungated one is refused, citing spec §5 invariant 5. requires: [evidence] is not a substitute — recording a citation is the agent's act, promotion is the gate's. This is what makes the direct-set gate un-opt-out-able: cell set --state hardened is refused only while every declared entry into hardened is gated, so before this rule one ungated transition declare switched that refusal off for the whole project. Transitions out of done (regress, reopen) and into excluded/waived are unaffected — they are not promotion.

The done-state slug is hardened — use it (not done) in any transition example, because --to done names no state and hits the honesty gate.

To see the result of any tweak, read the effective ladder with defaults show (above) — it renders the resolved states/transitions/gates with each element tagged source=default|project plus the hidden base states, so you can confirm exactly what a tweak moved. The defaults subcommands are documented in full under Definition of Done — Commands.

See also

• Cells · Dimensions · Milestones & DoD · Why lettuce

Four readers consume lettuce's output, and each owns one surface:

| reader | surface | contract | |---|---|---| | agent automation, integrators, HTTP | --format json (and yaml) | the complete, stable envelope {ok, data, warnings, meta} | | a human at a terminal | --format table (the default) | the complete human rendering: headers, ordinals, alignment, (none), the <command> ok acknowledgement | | a shell pipeline | --format plain | newline-separated primary references | | documents, diagrams, the board page | markdown, html, okf, mermaid, dot | the document, scoped to the commands that produce it |

The operator ruled on 2026-09-27 that plain belongs to the pipeline and has one meaning everywhere (ADR 0026, rulings D1-D4). A field you want to read is on table (to look at) or json (to parse). Plain answers only "which objects?", so that

lettuce task list --status ready --format plain | xargs -n1 lettuce task show --format json

works for every command, not just the ones that happen to collapse.

Output kinds

Every catalog command declares the KIND of its successful stdout. lettuce usage --format json publishes it per command as output_kind (and output_record, the record kind whose reference it prints). The kind is a property of the command, never inferred from the payload's shape — the old shape-keyed rules are how every "plain changed when the data changed" defect arose (LET-900).

| kind | what it is | --format plain prints | |---|---|---| | object | one record: most shows, and every mutation that creates or changes ONE object | exactly its primary reference, one line | | collection | 0..N records: every list, the queries, audits, bulk mutations (task set-where, cell set-where/clear-where/import/reconcile, cell verify/affirm); lease show is a 0..1 collection | one primary reference per row, in order; nothing (zero bytes, exit 0) when empty | | report | a computed document with no enumerable identities: status, doctor, validate, dod show, defaults show, grid show, board next, and the configuration/maintenance mutations (dod, defaults, import, repair, recover, cleanup, reconcile, sync) | the table bytes, byte-identical | | verdict | a yes/no answer about a subject: task exists, cell gate check, graph-run-case conform, graph-def lint | the subject's reference iff the answer is yes; nothing on stdout otherwise, the explanation on stderr; the exit code is the answer | | content | a document or byte payload that IS the product: usage, skill, docs, board render, the viz diagrams | the content (artifact file get: the raw file bytes) |

Rules that complete the picture

• Mutations print what they changed (ruling D2). REF=$(lettuce task create TSK-9 --title x --format plain) sets REF to the new task's reference; a delete prints the deleted reference; a bulk mutation prints one reference per affected row. The <command> ok acknowledgement stays on table. Project configuration with no record identity (dod set, defaults …, import, repair …) is declared a report and prints the table bytes.
• Inclusion flags are refused under plain (ruling D1). --with-*, --full and --body-versions ask for CONTENT, which plain cannot carry: lettuce task show TSK-1 --full --format plain is refused FW-CMD-USAGE, naming --format table and --format json, on objects and collections alike, locally and in hosted client mode. (--include-archived widens the row set, not the content, and stays legal.)
• An explicit projection prints the requested columns, tab-separated and headerless, one row per line (query run … select …, query tasks --fields …). This is the one sanctioned widening of "references": the caller named the columns. --refs-only asks for references while naming fields on query tasks. --group-by asks for buckets and prints them exactly as table does.
• Verdicts are filters (ruling D3). … | xargs -n1 lettuce task exists --format plain prints the references that exist; the exit code is 0 for yes and 2 for no in every format, for every verdict (task exists, cell gate check, graph-def lint, graph-run-case conform). Exit 1 means the command itself failed (ok:false). lettuce usage <command> --format json publishes each command's exit_codes.
• Rows that are not a clean answer are named on stderr (R1a). lease list prints one task reference per lease — the same row set as json — and names the rows whose task could not be judged; task set-where names the rows that failed. The row set never changes with the format.
• Errors leave stdout empty and print lettuce: error [CODE]: … plus -> action on stderr; warnings go to stderr. Both are the same under plain and table.
• Never: zero bytes for an object, report or a yes verdict; a different object than the one read (a carrier's refs, a project's authors); the input echoed as the answer; a shape that follows the data.

Primary references

The primary reference of a record is the token its own show command accepts as its identity, spelled in its §16.5 form where one exists — so every reference plain prints round-trips into that command (TestOutputContract checks it for every kind that has a show — events round-trip into query audit, workflow transitions into workflow transition show, grid scopes into grid scope show; only kinds with no show command at all — authors, id blocks, evidence rows, dimension members, migrate sessions, domains, paths — are named by the command that takes them).

| record kind | primary reference | example | |---|---|---| | task (also a lease, a task-graph node) | {project}/{task} | p/TSK-1 | | comment, run, run log, run summary, artifact, version | the §16.5 sub-object form | p/TSK-1/run/run_…/log/log_… | | registry object, milestone, workflow | {project}/{kind}/{slug} | p/milestone/m1 | | workflow transition | {project}/workflow/{workflow}/transition/{n} (workflow transition show takes it) | p/workflow/default/transition/3 | | saved query | {project}/{slug} (its event target {project}/saved-query/{slug} is also accepted as input) | p/ready | | event | {object reference}/event/{id} — ONE spelling in task audit, query audit, query timeline and FQL from events: a registry object in its singular §16.5 form, a saved query {project}/saved-query/{slug}, the project ledger {project}; query audit takes it and answers that one event | p/TSK-1/event/evt_…, p/label/red/event/1 | | project | its name | p | | author | its name | a1 | | cell | its coordinate (cell show also accepts the {project}/cells/{hash} spelling FQL rows carry) | area=auth;layer=api | | cell evidence row | its index — what cell evidence remove --index takes, not its ref pointer | evd_… | | dimension, graph definition, grid scope | slug (grid scope show is an object) | rp | | dimension member | member slug | unit-a | | graph pattern | name@vN | review-panel@v1 | | graph-run-case, carrier | id | grc_…, car_… | | id block | its first id | LET-2000 | | migrate session | session id | mig_… | | domain | name | acme | | store (init) / bundle (export) | the path | /data/store |

FQL rows (query run) and search hits (query search --scope all) mix kinds: each row prints its own reference.

Every command

The table below is generated from the declarations (outputContracts) and guarded: a test fails if it differs from what the binary declares, and TestOutputContract fails if the binary's output differs from the declaration.

| command | output kind | --format plain prints | |---|---|---| | usage | content | the content, as table prints it | | skill | content | the content, as table prints it | | docs | content | the content, as table prints it | | docs list | collection | one concept reference (the row itself) per row of concepts; nothing when empty | | docs show | content | the content, as table prints it | | docs export | object | its docs-export reference (out) | | okf | content | the content, as table prints it | | version | report | the table bytes | | self-update | report | the table bytes | | init | object | its store reference (root) | | status | report | the table bytes | | agents | collection | one author reference (name) per row of agents; nothing when empty | | work | report | the table bytes | | validate | report | the table bytes | | doctor | report | the table bytes | | recover | report | the table bytes | | cleanup | report | the table bytes | | reconcile | report | the table bytes | | author add | object | its author reference (author) | | author list | collection | one author reference (the row itself) per row of authors; nothing when empty | | author deactivate | object | its author reference (author) | | author reactivate | object | its author reference (author) | | project create | object | its project reference (project) | | project set-name | object | its project reference (project) | | project rename | object | its project reference (new_project) | | project merge | object | its project reference (target_project) | | project list | collection | one project reference (the row itself) per row of projects; nothing when empty | | project show | object | its project reference (project) | | project archive | object | its project reference (project) | | project unarchive | object | its project reference (project) | | project move | object | its project reference (project) | | project delete | object | its project reference (project) | | project id-block grant | object | its id-block reference (first_id) | | project id-block list | collection | one id-block reference (first_id) per row of blocks; nothing when empty | | project author add | object | its author reference (author) | | project author list | collection | one author reference (the row itself) per row of authors; nothing when empty | | registry create | object | its registry-object reference (reference) | | registry update | object | its registry-object reference (reference) | | registry list | collection | one registry-object reference (reference) per row of items; nothing when empty | | registry show | object | its registry-object reference (reference) | | milestone create | object | its milestone reference (reference) | | milestone list | collection | one milestone reference (reference) per row of items; nothing when empty | | milestone show | object | its milestone reference (reference) | | milestone close | object | its milestone reference (reference) | | milestone reopen | object | its milestone reference (reference) | | milestone set-stage | object | its milestone reference (reference) | | workflow list | collection | one workflow reference (reference) per row of items; nothing when empty | | workflow show | object | its workflow reference (reference) | | workflow transition list | collection | one workflow-transition reference ({^project}/workflow/{^workflow}/transition/{number}) per row of transitions; nothing when empty | | workflow transition show | object | its workflow-transition reference (reference) | | workflow revise | object | its workflow reference ({project}/workflow/{workflow}) | | task create | object | its task reference (reference) | | task show | object | its task reference (reference) | | task list | collection | one task reference (reference) per row of tasks; nothing when empty | | task exists | verdict | the task reference (reference) iff exists is true; nothing otherwise (the explanation on stderr; the exit code is the answer) | | task set | object | its task reference (reference) | | task set-where | collection | one task reference (reference) per row of results; nothing when empty; rows it could not judge, or that failed, named on stderr | | task unset | object | its task reference (reference) | | task set-list | object | its task reference (reference) | | task transition | object | its task reference (reference) | | task clone | object | its task reference (reference) | | task reopen | object | its task reference (reference) | | task archive | object | its task reference (reference) | | task unarchive | object | its task reference (reference) | | task delete | object | its task reference (reference) | | task body add | object | its task reference (reference) | | task audit | collection | one event reference (reference) per row of events; nothing when empty | | task graph | collection | one task reference (reference) per row of nodes; nothing when empty | | custom set | object | its task reference (reference) | | custom clear | object | its task reference (reference) | | comment add | object | its comment reference (reference) | | comment edit | object | its comment reference (reference) | | comment status | object | its comment reference (reference) | | comment list | collection | one comment reference (reference) per row of comments; nothing when empty | | comment show | object | its comment reference (reference) | | comment archive | object | its comment reference (reference) | | comment unarchive | object | its comment reference (reference) | | comment delete | object | its comment reference (reference) | | lease acquire | object | its lease reference (reference) | | lease renew | object | its lease reference (reference) | | lease release | object | its lease reference (reference) | | lease steal | object | its lease reference (reference) | | lease show | collection | its lease reference (reference) when present is true, nothing otherwise (a 0..1 collection) | | lease list | collection | one lease reference (reference) per row of leases; nothing when empty; rows it could not judge, or that failed, named on stderr | | run start | object | its run reference (reference) | | run finish | object | its run reference (reference) | | run log add | object | its run-log reference (reference) | | run summary add | object | its run-summary reference (reference) | | run list | collection | one run reference (reference) per row of runs; nothing when empty | | run show | object | its run reference (reference) | | run log list | collection | one run-log reference (reference) per row of logs; nothing when empty | | run log show | object | its run-log reference (reference) | | run summary list | collection | one run-summary reference (reference) per row of summaries; nothing when empty | | run summary show | object | its run-summary reference (reference) | | artifact add | object | its artifact reference (reference) | | artifact replace | object | its artifact reference (reference) | | artifact list | collection | one artifact reference (reference) per row of artifacts; nothing when empty | | artifact show | object | its artifact reference (reference) | | artifact archive | object | its artifact reference (reference) | | artifact unarchive | object | its artifact reference (reference) | | artifact delete | object | its artifact reference (reference) | | artifact file get | content | the raw file bytes | | version add | object | its version reference (reference) | | version list | collection | one version reference (reference) per row of versions; nothing when empty | | version show | object | its version reference (reference) | | query run | collection | one row reference (reference) per row of rows; nothing when empty; an explicit projection prints the requested columns, --group-by the buckets (as table) | | query search | collection | one search-hit reference (reference) per row of hits; nothing when empty | | query tasks | collection | one task reference (reference) per row of rows; nothing when empty; an explicit projection prints the requested columns, --group-by the buckets (as table) | | query audit | collection | one event reference (reference) per row of events; nothing when empty | | query timeline | collection | one event reference (reference) per row of events; nothing when empty | | query graph | report | the table bytes | | query saved create | object | its saved-query reference (reference) | | query saved update | object | its saved-query reference (reference) | | query saved archive | object | its saved-query reference (reference) | | query saved unarchive | object | its saved-query reference (reference) | | query saved list | collection | one saved-query reference (reference) per row of saved_queries; nothing when empty | | query saved show | object | its saved-query reference (reference) | | query saved run | collection | one row reference (reference) per row of result.rows; nothing when empty; an explicit projection prints the requested columns, --group-by the buckets (as table) | | export | object | its bundle reference (bundle) | | import | report | the table bytes | | migrate | report | the table bytes | | migrate verify | report | the table bytes | | migrate status | report | the table bytes | | migrate list | collection | one migrate-session reference (session_id) per row of sessions; nothing when empty | | migrate abandon | object | its migrate-session reference (session_id) | | migrate release | object | its migrate-session reference (session_id) | | migrate rollback | object | its migrate-session reference (session_id) | | repair plan | report | the table bytes | | repair check | report | the table bytes | | repair apply | report | the table bytes | | repair automatic | report | the table bytes | | sync status | report | the table bytes | | sync push | report | the table bytes | | sync pull | report | the table bytes | | conflict bundle | object | its conflict-bundle reference (bundle_id) | | serve | report | the table bytes | | domain create | object | its domain reference (name) | | domain list | collection | one domain reference (name) per row of domains; nothing when empty | | client list | collection | one client reference ({subject}/{actor}@{client_version}) per row of clients; nothing when empty | | github init-repo | object | its github-repository reference (repository.full_name) | | cell list | collection | one cell reference (coordinate) per row of cells; nothing when empty | | cell rollup | report | the table bytes | | cell evidence list | collection | one evidence reference (index) per row of evidence; nothing when empty | | cell evidence add | object | its evidence reference (index) | | cell evidence remove | object | its evidence reference (index) | | cell gate check | verdict | the cell reference (coordinate) iff passed is true; nothing otherwise (the explanation on stderr; the exit code is the answer) | | cell show | object | its cell reference (coordinate) | | cell set | object | its cell reference (coordinate) | | cell clear | object | its cell reference (coordinate) | | cell set-where | collection | one cell reference (coordinate) per row of set or coordinates; nothing when empty; its report findings announced on stderr | | cell clear-where | collection | one cell reference (coordinate) per row of cleared or coordinates; nothing when empty; its report findings announced on stderr | | cell note | object | its cell reference (coordinate) | | cell import | collection | one cell reference (coordinate) per row of set or assertions; nothing when empty; its report findings announced on stderr | | cell transition | object | its cell reference (coordinate) | | cell verify | collection | one cell reference (coordinate) per row of confirmed, or the one cell it acted on | | cell affirm | collection | one cell reference (coordinate) per row of confirmed, or the one cell it acted on | | board export | report | the table bytes | | board next | report | the table bytes | | board render | content | the content, as table prints it | | cell reconcile | collection | one cell reference (coordinate) per row of regressed; nothing when empty; its report findings announced on stderr | | dimension list | collection | one dimension reference (slug) per row of dimensions; nothing when empty | | dimension show | object | its dimension reference (slug) | | dimension member list | collection | one dimension-member reference (member) per row of members; nothing when empty | | dimension member add | object | its dimension-member reference (member) | | dimension member update | object | its dimension-member reference (member) | | dimension declare | object | its dimension reference (slug) | | dimension rename | object | its dimension reference (new_dimension) | | dimension close | object | its dimension reference (dimension) | | dod set | report | the table bytes | | dod clear | report | the table bytes | | dod show | report | the table bytes | | defaults show | report | the table bytes | | defaults state declare | report | the table bytes | | defaults state set-default | report | the table bytes | | defaults state hide | report | the table bytes | | defaults transition declare | report | the table bytes | | defaults transition hide | report | the table bytes | | defaults gate declare | report | the table bytes | | defaults reset | report | the table bytes | | grid scope add-unit | object | its grid-scope reference (scope) | | grid scope add-dim | object | its grid-scope reference (scope) | | grid scope remove-unit | object | its grid-scope reference (scope) | | grid scope remove-dim | object | its grid-scope reference (scope) | | grid scope show | object | its grid-scope reference (scope) | | grid show | report | the table bytes | | graph-def create | object | its graph-def reference (slug) | | graph-def revise | object | its graph-def reference (slug) | | graph-def show | object | its graph-def reference (slug) | | graph-def list | collection | one graph-def reference (slug) per row of items; nothing when empty | | graph-def compile | object | its graph-def reference (slug) | | graph-def lint | verdict | the graph-def reference (slug) iff clean is true; nothing otherwise (the explanation on stderr; the exit code is the answer) | | graph-def viz | content | the content, as table prints it | | graph-def catalog list | collection | one graph-pattern reference (key) per row of patterns; nothing when empty | | graph-def catalog show | object | its graph-pattern reference (pattern.key) | | graph-def use | object | its graph-def reference (slug) | | graph-run-case open | object | its graph-run-case reference (id) | | graph-run-case advance | object | its graph-run-case reference (id) | | graph-run-case close | object | its graph-run-case reference (id) | | graph-run-case abandon | object | its graph-run-case reference (id) | | graph-run-case acknowledge | object | its graph-run-case reference (id) | | graph-run-case show | object | its graph-run-case reference (id) | | graph-run-case viz | content | the content, as table prints it | | graph-run-case list | collection | one graph-run-case reference (id) per row of cases; nothing when empty | | graph-run-case conform | verdict | the graph-run-case reference (id) iff conforms is true; nothing otherwise (the explanation on stderr; the exit code is the answer) | | graph-run-case refs-to | collection | one graph-run-case reference (graph_run_case) per row of references; nothing when empty | | carrier produce | object | its carrier reference (id) | | carrier list | collection | one carrier reference (id) per row of carriers; nothing when empty | | carrier show | object | its carrier reference (id) | | carrier acknowledge | object | its carrier reference (id) |

Migrating a script

If a script parsed --format plain as a field listing, it was reading the human surface. Switch it to --format json (fields under .data; a mutation's produced object is under .data.data) or, to look at the output yourself, --format table. docs/operations/RELEASE-NOTES.md lists every command whose plain output changed in v0.20.0, before and after.

FQL (the lettuce query language) reads the store deterministically. Shape:

from SOURCE [where EXPR] [select f1,f2] [order by f [desc]] [limit N] [offset N]

• Sources: tasks, events, registry, authors, projects, dimensions (the active pack's declared dimensions), cells (stored cell assertions — sparse defaults are not rows).
• Strings use double quotes (single quotes are rejected). contains matches case-insensitively unless --case-sensitive.
• Task-reference fields — parent, depends-on, blocks — are stored project-qualified (proj/TASK-1), and the comparison operand is canonicalised against --project before matching. Both spellings therefore find the same rows: where parent = "TASK-1" is equivalent to where parent = "proj/TASK-1". Before v0.15.0-3312 only the qualified spelling matched: the bare one returned an empty result at exit 0 rather than an error, so if an older build reports no rows for a relation you can see on disk, that is why.
• --group-by FIELD (tasks source only) buckets by assignee, component, milestone, severity, status, type, or workflow.
• Soft-archived tasks are hidden from every query/list surface by default; pass --include-archived.

lettuce query run "from tasks where status = active select task,title" --root "$ROOT" --format json
lettuce task show "$P/TASK-1" --with-body --format json     # or --full
lettuce task audit "$P/TASK-1" --format json                # event history
lettuce query timeline ...                                  # chronological events

Querying coverage with the cells source

The cells source interrogates the coverage plane the same way you query tasks. Stored fields: coordinate, state, hash (plus cell/project/pack identity). It also carries DoD-derived axes:

| Axis | Values | Meaning | |---|---|---| | freshness | fresh | aging | stale | how current the cell's evidence is | | depth | int | distinct-revision confirmation count | | dod | blocking | met | is this cell blocking the Definition of Done | | dod-reason | grade | depth | recency | unknown | why a blocking cell blocks |

These turn "what is not yet done?" into a query:

lettuce query run "from cells where dod = blocking select coordinate,state" --project "$P" --format json
lettuce query run "from cells where freshness = stale select coordinate" --project "$P" --format json
lettuce query run "from cells where depth >= 2 select coordinate" --project "$P" --format json
lettuce query run "from cells where dod-reason = grade select coordinate" --project "$P" --format json

Slicing by scope / member

FQL has no dedicated scope/unit/dimension filter operator today — slice by a coordinate member instead: where coordinate contains "layer=api" or where coordinate contains "scope=login". See scopes.

Saved queries

lettuce query saved create <slug> --title "<title>" --fql "<fql>" --project P --author A
lettuce query saved run <name> --project P
lettuce query saved list --project P

See also

• Queries — Commands (all query/query saved subcommands)
• Cells · Scopes · Milestones & DoD
• The plain format — what --format plain emits, and when an explicit projection changes it

A scope is the reserved partition by which the Definition of Done and the board evaluate coverage. It is a modeled dimension, but a special one: scope is how a project carves its quality space into evaluable regions (e.g. scope=auth, scope=login, scope=storage).

How to shape scopes

Scopes are declared implicitly by the cells that use them — you assert cells at coordinates that include a scope= member, and those scope values become the partitions the board and DoD report on. Which units and dimensions belong to a scope is a modeling choice: a scope groups the coordinates whose scope= member matches, across whatever other dimensions those coordinates declare.

lettuce cell set "scope=auth;layer=api"  --state in_progress --project P --author A
lettuce cell set "scope=auth;layer=db"   --state planned    --project P --author A
lettuce board next --project P --scope auth     # steer within one scope
lettuce cell rollup --by scope --project P       # per-scope floor + hardened ratio

The unscoped bucket (honesty invariant)

A cell that declares no scope= is bucketed under the synthetic scope unscoped at evaluation time — so it is never silently outside the DoD frame. You cannot assert scope=unscoped on a cell; the name is reserved for that bucket. This guarantees every asserted cell is accounted for by exactly one scope when the DoD verdict is computed.

Board & DoD interplay

• board next --scope <name> steers within one scope; naming an undeclared scope returns an honest error listing available scopes (never a silent empty report).
• dod set can declare a grade floor per project and/or per scope; the board's leading DoD: … line is the computed verdict against that floor.
• grid scope add-unit / add-dim declare a scope's coverage grid — its units × applicable dims — which sets the scope's honest denominator (every un-worked coordinate counts as an implicit-untested cell), independent of how many cells are actually stored.

See also

• Cells · Dimensions · Milestones & DoD
• Cells — Commands (board, cell rollup --by scope)

Canonical state lives in a store — a path-jailed root of ordinary files. Files are the source of truth: you can inspect, diff, and validate the store with normal tools. The two checks differ: lettuce validate --strict verifies the store is well-formed (grammar), but it is silent on a derived scalar forged out of band — a hand-edited task status passes it. lettuce doctor is what tells you the store is healthy: it additionally catches that derived/status drift (FW-STORE-DERIVED-DRIFT) that validate --strict does not, and tells you how to repair it (their divergence is tracked in LET-1723).

Foundational invariants

• Files are the source of truth. No hidden database; every object is a file.
• Mutations are explicit and attributed. Always pass --project and --author; lettuce never infers them from the OS, Git config, or store contents. Every mutation is recorded as an event (task audit, query timeline).
• Concurrency is coordinated by leases and revisions. Claim work with a lease before touching it; pass --expect-revision N when retrying or racing another agent. Writes are serialized by a single-writer generation lock.
• Output is a stable envelope. With --format json|yaml, every result is { ok, data, warnings, meta }; errors are { ok:false, error:{ code, message, diagnostics:[...] } } with machine-readable diagnostic codes.

The two data planes

| Plane | Objects | Question it answers | |---|---|---| | Work | projects, tasks, workflow, leases, runs, artifacts, comments | what is being done, by whom, with what evidence | | Coverage | packs, dimensions, members, cells, gates, boards | how proven each part of the product is |

The two planes meet at evidence: a task on the Work plane is linked as the evidence that hardens a cell on the Coverage plane.

Store modes

• filesystem (default, offline) — canonical state under the store root.
• dedicated-git — a strongly-consistent shared store that fetches upstream before every mutation (requires connectivity by design).
• client — set a server URL to drive a running lettuce serve over HTTP instead of mounting the store.

See also

• Core & Runtime — Commands (init, validate, doctor, recover, cleanup)
• Tasks · Cells · Getting started

A task is the unit of work on the Work plane. Tasks live under a project, carry a stable reference (project/TASK-ID), and move through a workflow of states via validated transitions.

Lifecycle

lettuce task create LET-1 --project P --author A --title "..." --body "..."
lettuce task show P/LET-1 --with-body
lettuce task transition P/LET-1 <transition> --project P --author A   # only legal moves
lettuce task list --project P

• Workflow is supplied by the active pack: which states exist and which transitions are legal. An illegal transition is refused, not recorded (lettuce workflow list / workflow show).
• Stable references — project/TASK-ID is durable across renames; prefer it when project context is ambiguous.
• Attribution & audit — every mutation records an event; inspect with task audit and query timeline.

Coordination for agents

• Leases — claim a task before working it: lettuce lease acquire (atomic, expiring, audited). Renew with lease renew; steal only expired leases. This is the honest alternative to a "who's working on it" naming convention.
• Revisions — pass --expect-revision N on event-bearing mutations when retrying or racing another agent; a stale revision is rejected.

Recording execution (evidence)

• Runs — run start / run finish, with run log add and run summary add — the record of an execution attempt.
• Artifacts — artifact add / replace attach outputs to a task.
• Comments — comment add for human/agent narrative.

A finished task becomes evidence: link it to a cell (cell evidence add --kind task) to harden coverage. Work hardens cells; cells reveal work.

Task-local objects

Comments, leases, runs, and artifacts are task-local — 35 subcommands in the Task-Local-Objects group.

See also

• Dependencies — what depends-on asserts — depends-on/blocks, and which end is ready to start
• Tasks — Commands · Task-Local Objects — Commands
• The store & two planes · Cells · Queries (FQL)

Workflow is the model of legal states and the transitions between them. It is supplied by the active pack as data — not hard-coded — and it governs both tasks (the work plane) and cells (the coverage plane).

lettuce workflow list --project P              # available workflows
lettuce workflow show <name> --project P       # its states + transitions
lettuce workflow transition list --project P   # the legal moves

Validated transitions

A transition moves an object from one state to another only along a declared, legal edge. An illegal move is refused, not recorded:

lettuce task transition "$P/TASK-1" start-work --project P --author A   # -> ok: true (A holds the lease)
lettuce task transition "$P/TASK-1" start-work --project P --author A   # -> FW-WF-TRANSITION-NOT-ALLOWED: already started
# positional: lettuce task transition REF ACTION [--reason TEXT] [--expect-revision N]

• Some transitions are requirement-gated — e.g. start-work needs an active lease; without it, the move fails with FW-WF-REQUIREMENT-UNSATISFIED.
• --expect-revision N guards against racing another agent (a stale revision is rejected).

Gates (coverage plane)

On cells, a gate authorizes a gated transition. Built-in evaluators:

• guard-bite — the cell has ≥1 authorising evidence link: a --kind task link to a task that is done and carries custom/grc (its verified close walk). A --kind url link annotates but never authorises.
• consistency — store predicates recompute clean.

cell transition refuses a gated move that fails its gate (FW-WF-GATE-UNSATISFIED) unless --facilitate records the verdict but allows the move.

> Never --facilitate past a failed gate to "make progress." One unproven > green poisons every future orientation. See agentic cycles.

See also

• Registries & Workflow — Commands (workflow subcommands)
• Tasks · Cells · Packs

lettuce is not primarily an autonomy tool — every command works one at a time, human or agent. But one powerful way to use it: if you are an agent with standing goals and a store, run lettuce as your loop. The store read forward is the plan; the store written backward is the proof — no external planner needed.

The core loop (one task at a time)

ROOT=.lettuce; P=myproject; A=my-agent
# 1. Once: seed a store (idempotent).
lettuce init --root "$ROOT" --author "$A" --bootstrap-project "$P" --bootstrap-author --idempotent --format json
# 2. Discover — concrete items AND the coverage frontier.
lettuce task list --project "$P" --root "$ROOT" --format json
lettuce board next --project "$P" --root "$ROOT" --format json
# 3. Create work.  4. Claim (lease) then start.  5. Record runs/artifacts.  6. Complete + release lease.
lettuce lease acquire "$P/TASK-1" --expires-at "$(date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v+1H +%Y-%m-%dT%H:%M:%SZ)" --project "$P" --author "$A" --format json
lettuce task transition "$P/TASK-1" start-work --project "$P" --author "$A" --format json
# ... work, narrate with `run log add` / `comment add`, attach `artifact add` ...
lettuce task transition "$P/TASK-1" complete --reason "Done + verified" --project "$P" --author "$A"
lettuce lease release "$P/TASK-1" --project "$P" --author "$A"

> Lease-gated transitions (start-work) fail with FW-WF-REQUIREMENT-UNSATISFIED > unless you hold the lease. Acquire first. Transition syntax is positional: > lettuce task transition REF ACTION [--reason TEXT] [--expect-revision N].

The autonomous cycle — orient → act → reflect → file

# ORIENT — ask the store what matters most right now.
lettuce board next --project "$P" --root "$ROOT" --format json
#   → every scope's meter weakest-first, shape-aware suggestions, concrete
#     gap/untested coordinates, each with the exact drill command (--depth 0|1|2).
#     Pick ONE target: gap (known defect) before untested (undiscovered),
#     weakest scope first. Act on the coordinate it printed — don't hand-compose one.

# ACT — make the work claimed, attributed, and visible.
lettuce task create TASK-N --title "Harden <coord>" ...
lettuce lease acquire "$P/TASK-N" ...; lettuce task transition "$P/TASK-N" start-work ...

# REFLECT — record what happened WITH evidence, then close the cell.
lettuce artifact add "$P/TASK-N" --type test-report ...          # the proof itself
lettuce task transition "$P/TASK-N" complete --reason "guard bites" ...
lettuce cell evidence add "<coord>" --ref "$P/TASK-N" --kind task ...
lettuce cell transition "<coord>" harden ...                    # guard-bite gate must pass

# FILE — organize everything you discovered before looping.
lettuce task create ...                             # one ticket per unfixed finding
lettuce cell set "<coord>" --state gap --reason "<defect>" ...  # defects get addresses
lettuce dimension member add <dim> <member> ...     # new surface → new map row
lettuce milestone set-stage <slug> --stage <s> ...  # progress the hypothesis ladder
lettuce cell reconcile ...                          # regress stale greens
lettuce validate --strict ...

Then run board next again — the frontier has changed, partly because you hardened a cell and partly because you filed what you found. Work hardens cells; cells reveal work. FILE is not bookkeeping — it is how the map stays truthful enough to steer the next iteration.

What board next needs to be useful

• A store and a valid --project (a missing/unknown project is refused — no default, no cross-project scan).
• At least one stored cell — the frontier is built from asserted cells only; sparse pack-defaults are never rows. An empty board is not an error (every scope meter reads n/a).
• A declared DoD to get the leading DoD: … verdict line (dod set).
• --depth accepts only 0, 1, 2; --scope <name> naming an undeclared scope returns an honest error listing available scopes, never a silent empty.

The invariant that keeps the loop honest

A gap/untested cell spawns a task (the cell is the work's address); the finished task, linked as evidence, authorizes hardening (cell transition is guard-bite gated); and if the cited evidence later unresolves, cell reconcile machine-regresses the cell. Neither direction can lie to the next iteration — which is why you never --facilitate past a failed gate to "make progress": one unproven green poisons every future ORIENT.

Sharing the board: export and render

board next steers your loop; two sibling read-only projections publish the same board for a human or a dashboard, from the identical BoardExport:

• board export emits a stable, versioned JSON data contract on stdout (schema_version, the pack's dimension/state legend, the stored cells with evidence, per-axis coverage rollups, the blended headline ratio, milestones, tickets, and the activity histogram). It is data ⟂ visual: the document carries no styling, so a separate renderer owns the presentation.
• board render turns that same export into a self-contained HTML page natively in Go (no Python, no JSON round-trip) — you pipe stdout to a file. Every byte is inline: no src=, no external references, and no network call of any kind. The page is pure-CSS with one authorized exception — a project carrying graph-run-cases also emits the grc replay simulator as exactly one inline <script> plus one inert <script type="application/json"> data island per grc; a project without graph-run-cases emits no <script> at all. --theme selects only the CSS frame (today the sole built-in is default; an unknown name is refused with the available list). Both default their provenance from the store (data revision + latest-event instant), never the wall clock, so a render is reproducible; --source-rev stamps an explicit revision into the masthead.

Both require --project and read only that project — no cross-project scan.

The activity/velocity band is store operations, not git commits. The board's histogram is derived purely from stored event timestamps (a per-calendar-day count of store mutations), bucketed into ISO weeks. It is deliberately the self-containable substitute for git-commit velocity — the board never reads a git repo, which is what keeps the HTML fully offline and portable. Read it as "how much work landed in the store over time", not as a commit log.

See also

• Cells · Tasks · Milestones & DoD
• Cells — Commands (board next, board export, board render, cell rollup, cell reconcile)
• Why lettuce — determinism is what makes the loop trustworthy.

The Agentic cycles guide gives you the theory of the orient→act→reflect→file loop and the invariant that keeps it honest. This guide walks one concrete loop, showing at every step what lettuce hands you (GET) and what you do with it (DO). The commands are real, and so is every GET block: it is what the binary prints for the store the step describes (a guard runs each one; … marks elided lines and run-specific ids).

The scenario. A webapp project on the shipped coverage convention (the default — every project runs it with nothing to enable). To keep the board compact, this walkthrough grades a deliberately small slice: two coverage axes, a (Functional correctness) and i (Security), across an auth scope (fully hardened) and a checkout scope (weak). Our job this cycle: harden one cell. We do not choose it — the board does.

> New to a project? Start with First contact. Standing > a project up from nothing? Use the Project setup > playbook.

Step 1 — ORIENT · GET the frontier and the DoD verdict

DO: ask the store what matters most, and read the verdict first.

ROOT=.lettuce; P=webapp; A=codex-01
lettuce board next --root "$ROOT" --project "$P" --depth 1 --format plain

GET:

board next · project webapp · DoD: NOT DONE (1/2 scopes met) · 2 open cell(s)
  DoD bar: hardened
  DoD-blocked (close these to reach done):
    [✕] checkout checkout — 0/2 DoD-applicable met (2 below bar)
        ↳ re-verify: lettuce board next --project webapp --scope checkout --depth 2
start here: checkout / dim=a;scope=checkout;unit=cart  [In_progress · Functional correctness]
  ↳ asks: Specified output for valid input across the happy path and every flag.
  ↳ state: Work on this cell is underway; nothing is proven yet. Next: link the evidence the work produced.
  ↳ detail: lettuce cell show "dim=a;scope=checkout;unit=cart" --project webapp

[CHECKOUT] — 0.0% · 2 open
  • A    Functional correctness             0.0%  1I
      ↳ lettuce dimension show A --project webapp
  • I    Security (attack surface)          0.0%  1U
      ↳ lettuce dimension show I --project webapp
  ↳ full units + coordinates: lettuce board next --project webapp --scope checkout --depth 2

[AUTH] — 100.0% · 0 open
  • A    Functional correctness           100.0%  1H
  • I    Security (attack surface)        100.0%  1H

[UNVISITED] <n> of <n> coverage dimensions have NEVER been assessed — no cell names them.
…

(The report goes on to list the coverage axes no cell names yet and a ticket summary; they are elided here.)

What the store just told you, for free:

• The DoD verdict (NOT DONE (1/2 scopes met)) — the honest answer to "are we there yet?" — leads the report. auth is met; checkout blocks done.
• The single target — start here: names one coordinate, dim=a;scope=checkout;unit=cart, currently In_progress, with what the axis asks and what the state means. Take this coordinate verbatim; do not hand-compose one. Weakest scope, weakest cell, chosen deterministically.
• The drill commands — every line prints the exact lettuce … to descend.

Step 2 — ORIENT · GET the cell's own history

DO: before touching code, read what the target cell already knows.

lettuce cell show "dim=a;scope=checkout;unit=cart" \
  --root "$ROOT" --project "$P" --format table

GET — its current state, canonical coordinate (note the axes are sorted dim;scope;unit), pack, and any first-class note:

project    : webapp
state      : in_progress
coordinate : dim=a;scope=checkout;unit=cart
hash       : <id>
pack       : coverage
stored     : true

Now you know: this cell is a genuine open item on the coverage frontier, and your job is to move it to hardened — which the convention's harden gate will not let you do without proof.

Step 3 — ACT · claim the work, attributed and visible

DO: create a ticket for the change (if none exists), claim its lease, and start it. Leases make the claim atomic and prevent two agents fighting over the same work.

lettuce task create LET-2 --title "Test cart rejects tampered price" \
  --body "Add guard test." --root "$ROOT" --project "$P" --author "$A" --format plain
lettuce lease acquire webapp/LET-2 --expires-at "$(date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v+1H +%Y-%m-%dT%H:%M:%SZ)" \
  --root "$ROOT" --project "$P" --author "$A" --format plain
lettuce task transition webapp/LET-2 start-work \
  --root "$ROOT" --project "$P" --author "$A" --format plain

GET (--format plain prints each mutated object's reference; the missing-milestone advisory goes to stderr):

webapp/LET-2
webapp/LET-2
webapp/LET-2

> start-work is lease-gated: without the lease it fails > FW-WF-REQUIREMENT-UNSATISFIED. Acquire first. --expires-at is a required > RFC-3339 timestamp — the lease auto-expires so a crashed agent never wedges the > board.

...now do the actual engineering — write the failing test, make it pass, rebuild, and verify the guard bites (green → break the code → RED → fix → green). Narrate durable notes on the task as you go:

lettuce comment add webapp/LET-2 \
  --body "Guard added; verified it bites when price is tampered." \
  --root "$ROOT" --project "$P" --author "$A" --format plain

Step 4 — REFLECT · GET the honesty gate, DO record proof

DO: the cell is in_progress; walk it up the coverage ladder and attach the proving task as evidence. The harden transition is guard-bite gated: it refuses unless at least one linked evidence is a task that is done and carries custom/grc, the pin of the ticket-claim-verify run-case its close walk recorded (docs/guides/CLOSE-WALK.md). Linked evidence alone is not proof; finished, verified work is. Link it now and try harden while LET-2 is still open, and the store refuses:

C="dim=a;scope=checkout;unit=cart"
lettuce cell transition "$C" link-evidence --root "$ROOT" --project "$P" --author "$A" --format plain
lettuce cell evidence add "$C" --ref webapp/LET-2 --kind task \
  --root "$ROOT" --project "$P" --author "$A" --format plain
lettuce cell transition "$C" harden --root "$ROOT" --project "$P" --author "$A" --format plain   # -> FW-WF-GATE-UNSATISFIED

GET:

dim=a;scope=checkout;unit=cart
evd_<id>
lettuce: error [FW-WF-GATE-UNSATISFIED]: transition is blocked by its gate
  expected: gate guard-bite to pass (or --facilitate to record-not-enforce)
  actual:   guard-bite failed: 1 evidence link(s) present but none authorise: task webapp/LET-2 is active, not done

That refusal is the gate working. Close the ticket through its close walk, which completes it and pins custom/grc (a plain task transition … complete does not pin it, and harden keeps refusing with "done but carries no custom/grc run-case pin"), release the lease, then harden:

lettuce task transition webapp/LET-2 complete --reason "guard bites on tampered price" \
  --root "$ROOT" --project "$P" --author "$A" --format plain
lettuce lease release webapp/LET-2 --root "$ROOT" --project "$P" --author "$A" --format plain
lettuce cell transition "$C" harden --root "$ROOT" --project "$P" --author "$A" --format plain

Once LET-2 is done and pinned, the last command prints the cell's coordinate: the cell is hardened.

> Discipline, not shortcut. cell set --state hardened runs the same gate > and is refused the same way; only --facilitate gets past it, and that records > the bypass on the cell's event — an unproven green. Flip cells through > cell transition (gated), and reserve cell set for declaring planned / > blocked / waived / seeding. One unproven green poisons every future ORIENT.

Step 5 — FILE · DO organize what you discovered, GET the moved frontier

Found a second defect while working? File it as its own cell/ticket now, so the next ORIENT sees it. Then re-run the loop's first command — the frontier has moved, partly because you hardened a cell and partly because you filed what you found:

lettuce board next --root "$ROOT" --project "$P" --format plain

GET:

board next · project webapp · DoD: NOT DONE (1/2 scopes met) · 1 open cell(s)
  DoD bar: hardened
  DoD-blocked (close these to reach done):
    [✕] checkout checkout — 1/2 DoD-applicable met (1 below bar)
        ↳ re-verify: lettuce board next --project webapp --scope checkout --depth 2
start here: checkout / dim=i;scope=checkout;unit=cart  [Planned · Security (attack surface)]
  ↳ asks: …
  ↳ state: …
  ↳ detail: lettuce cell show "dim=i;scope=checkout;unit=cart" --project webapp

[CHECKOUT] — 50.0% · 1 open
  ↳ detail: lettuce board next --project webapp --scope checkout --depth 1

[AUTH] — 100.0% · 0 open
…

Checkout climbed 0.0% → 50.0%, the open count dropped from 2 to 1, and start here now points at the next weakest cell. That is the whole method: work hardens cells; cells reveal work.

Adapt this to your own cycle

• One cell per loop. Take the start here target, prove it, harden it, re-orient. Small, honest increments beat batch grading.
• Evidence is the currency. A cell reaches hardened only through the gated cell transition, with a real proving task linked. Never --facilitate past a failed gate to "make progress".
• Read the DoD first, every loop. board next leads with the verdict; when it reads DONE, you are actually done — measured, not asserted.
• The full ladder. This walkthrough graded a compact slice of the shipped coverage convention; its full ladder is untested → planned → in_progress → gap → evidence_linked → smoke → hardened, via plan / start / flag-gap / exercise / exercise-gap / link-evidence / harden (plus block / unblock / exclude / waive / regress / reopen) — the loop is identical across every axis. See the Project setup playbook.

See also

• Agentic cycles — the loop theory and the honesty invariant.
• First contact · Project setup playbook
• Cells · Tasks · Milestones & DoD
• Cells — Commands · Registries & Workflow — Commands

lettuce ships with working defaults, but leverage comes from wiring it into a real project deliberately: a store an agent can find, a pack that models the work, a Definition of Done floor that makes "done" a measurement, and saved reads that survive restarts. This guide covers every configuration surface and how to compose them.

The configuration precedence chain

Every resolvable setting follows one order, everywhere:

explicit flag  →  environment variable  →  --config JSON file  →  built-in default

| Setting | Flag | Env var | Default | |---|---|---|---| | Store root | --root PATH | LETTUCE_ROOT | nearest .lettuce walking up from the working directory, else refused (filesystem); cwd (dedicated-git) | | Project | --project NAME | LETTUCE_PROJECT | none — explicit where required | | Author | --author NAME | LETTUCE_AUTHOR | none — required for every mutation, never inferred | | Mode | --mode | LETTUCE_MODE | filesystem (other: dedicated-git) | | Output | --format | — | table (also plain, json, yaml; markdown only for doctor/usage/skill) | | Server URL | --server-url URL | LETTUCE_SERVER_URL (_FILE) | none. The --server-url flag switches the CLI to HTTP-client mode; LETTUCE_SERVER_URL does too unless a repo-local .lettuce is discovered, which overrides the env (the flag still wins). Fallback http://127.0.0.1:8727 | | Bearer / actor | --bearer | LETTUCE_BEARER (_FILE), LETTUCE_ACTOR (_FILE) | none | | Listen | serve --listen | LETTUCE_LISTEN | 127.0.0.1:8727 | | Config file | --config PATH | LETTUCE_CONFIG | none |

--config PATH is a JSON file for client context (server URL, bearer, actor) — useful when a machine drives a remote served store and you do not want tokens on the command line.

> --author is never inferred. lettuce refuses to guess the acting author > from the OS, Git config, or store contents. This is the honesty invariant that > makes every mutation attributable — set LETTUCE_AUTHOR once per agent so you > never forget it, but the tool will still never fill it in for you.

init — seeding a store idempotently

lettuce init --root .lettuce --author agent-1 \
  --bootstrap-project myproject --bootstrap-author --idempotent --format json

init requires a root but neither a project nor an author of its own; the flags bootstrap them in one call. It advertises idempotency_key=true and accepts the external-input keys bootstrap_project, bootstrap_author, idempotent, so --idempotent makes re-running it on an already-initialized store a success, not an error — safe to run on every agent wake as a cron-guarded seed step.

Each new project ships with the default workflow (open → ready → active → review → done, plus blocked/needs-human and terminals), the standard severities (low/medium/high/critical), task types (epic, story, task, bug, research, …), and artifact types — inspect them with lettuce workflow show default and lettuce registry list.

Root and project resolution

• --root is the path-jailed store root. Name it explicitly per project (.lettuce in the repo). There is no home-directory default: when no root is stated and none is discoverable by walking up from the working directory, the command refuses instead of guessing. That refusal is deliberate — two stores can each hold a project of the same name, so a wrong-store write succeeds silently and is discovered late.
• --project is a trusted context for shorthand references and project-scoped commands. There is no default-project pointer and no inference from store contents — a missing or unknown --project on a project-scoped command is refused (FW-NAME-PROJECT), never a silent cross-project scan. Use fully qualified references (myproject/TASK-1) when context is ambiguous.

Choosing a mode

| Mode | Activation | When to use | |---|---|---| | filesystem (default) | --mode filesystem / LETTUCE_MODE | Offline, single-worktree, canonical state under --root. The everyday choice. | | dedicated-git | --mode dedicated-git | A strongly-consistent shared store: every mutation is a Git commit and fetches upstream first. Requires connectivity by design — not an offline mode; needs a clean, synced worktree. sync status/push/pull manage it. | | HTTP client | --server-url (always), or LETTUCE_SERVER_URL when no repo-local .lettuce is discovered | The identical CLI dispatches over HTTP to a running lettuce serve instead of mounting the store. A discovered .lettuce overrides the env LETTUCE_SERVER_URL; the flag always wins. |

Pick filesystem for a local agent loop; dedicated-git when several writers share one authoritative store; client when the store lives behind a server. See serving lettuce safely for the client-mode auth posture.

Inspecting and tuning the convention

The shipped convention is the working model — states, transitions, gates, dimensions. lettuce ships exactly one, coverage, and every project runs it by default with nothing to enable. You inspect it and tune it per project rather than swapping it (every read needs a store root and --project):

lettuce dimension list  --project P            # the project's effective dimensions
lettuce dimension show A --project P            # one dimension by slug, full methodology
lettuce dod show        --project P            # the Definition-of-Done floor + verdict
lettuce grid show       --project P            # the declared coverage grid + denominator
lettuce board render    --project P            # the whole board as a self-contained HTML page

coverage is lettuce's 88-dimension / 15-family quality taxonomy. For that same convention with one project-specific adjustment, use the defaults layer — an additive per-project tweak over the ladder / gates / DoD — rather than authoring a whole new convention.

Author identity

Authors are stable, non-secret identifiers (codex-local-01, ci-agent, planner-agent) — one per acting agent.

lettuce author add planner-agent --idempotent                          # register YOUR name
lettuce project author add myproject planner-agent --author planner-agent --idempotent  # link YOURSELF
lettuce project author add myproject agent-2 --author planner-agent --idempotent        # a member links a registered teammate

--bootstrap-author on init/project create/project author add creates and links the author in the same call. Linking or bootstrapping YOUR OWN name is a writer act on a hosted server; bootstrapping ANOTHER name (project author add P <other> --bootstrap-author) registers someone else and needs admin on a server with an authz policy (LET-1885) — let the teammate register itself instead. See the membership table in the server security guide.

Saved queries — freezing the reads that matter

Reads an agent runs every cycle should be stored once, not retyped:

lettuce query saved create ready-tasks --project P --author A \
  --title 'Ready Tasks' --fql 'from tasks where status = ready select task,title'
lettuce query saved run ready-tasks --project P --format json
lettuce query saved update ready-tasks --fql '<new fql>' --expect-revision 1 --project P --author A
lettuce query saved list --project P

Saved queries are project-scoped, versioned (guard updates with --expect-revision), and archivable. Pair them with the reading surfaces so orientation is one command.

DoD floors — make "done" a measurement

A Definition of Done turns "are we there yet?" from an assertion into a computed verdict. Declare the floor once:

lettuce dod set --grade hardened --depth 2 --recency aging --project P --author A
lettuce dod set --scope s3 --depth 3 --project P --author A     # per-scope override
lettuce dod show --project P --format json                      # policy + verdict

• --grade (required for a first declaration) is the minimum pack state a cell must reach to count as done (validated against the active pack).
• --depth is an optional minimum distinct-revision confirmation depth (FRESH-2).
• --recency is an optional minimum freshness bucket (FRESH-3: fresh or aging, never stale).
• Without --scope you set project defaults; with --scope you override one scope's floors (unset fields inherit the default).

The verdict is a strict per-scope AND-gate — a scope is met only when every applicable cell clears the bar, never a blended percentage — and it layers two auto-derived outer gates you never set here: every committed milestone reached and zero non-terminal tickets. dod clear removes a floor or the whole policy.

Wiring lettuce in for maximum agentic leverage

The store is only leverage if an agent can rediscover it after a restart. Anchor the coordinates where they survive compaction — your CLAUDE.md (or equivalent always-injected instruction file), not memory:

1. Export the coordinates — LETTUCE_ROOT, LETTUCE_PROJECT, LETTUCE_AUTHOR so every command inherits them. 2. Cron-guard the seed — run idempotent init on each wake; it is a no-op on an existing store. 3. Model the work — declare project scopes/units on the default coverage convention (tune it with defaults if needed), assert the first cells. 4. Declare the bar — dod set a grade floor so board next leads with a verdict line. 5. Freeze the reads — saved queries for the frontier you check every cycle. 6. Run the loop — then board next both answers "are we done?" and hands you the next target.

Work that lives only in your context dies with your context; work reflected into the store is durable memory. That reflection is the whole point of configuring lettuce well.

See also

• The coverage convention · Scopes · Milestones & DoD
• How to read an existing store · Serving lettuce safely
• Running lettuce in autonomous agentic cycles

Your entry point may be lettuce.huru.ca or api.lettuce.huru.ca. You have no prior context. This guide is the fastest honest path from "just arrived" to "productively driving lettuce", written from your point of view. Every command below is real — run it.

> This is the entry point of the Agent Playbook. Once oriented, go to > Project setup playbook to prepare a > project, Agentic loop demo to watch one dev loop > end to end, and Agentic cycles for the loop theory.

Before Move 0 — get the binary and point it at a store

Lettuce is driven by the lettuce binary. The Huru hosted API is used through that binary — do not hand-craft curl/JSON against /v1/…; direct HTTP is discouraged and unsupported for agents.

1. Get the binary — pinned to the server's release. Your client must be the release the server runs. Ask the server (raw HTTP — you have no binary yet), download exactly that release FROM THE SERVER (your token is all it needs), verify its checksum:

   V=$(curl -fsS -H @<(printf 'Authorization: Bearer %s\n' "$LETTUCE_BEARER") https://api.lettuce.huru.ca/v1/version | jq -r .data.version)
   OS=$(uname -s | tr '[:upper:]' '[:lower:]'); ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
   curl -fsS -H @<(printf 'Authorization: Bearer %s\n' "$LETTUCE_BEARER") -o "lettuce-$OS-$ARCH" "https://api.lettuce.huru.ca/v1/client/$OS-$ARCH"
   curl -fsS -H @<(printf 'Authorization: Bearer %s\n' "$LETTUCE_BEARER") -o "lettuce-$OS-$ARCH.sha256" "https://api.lettuce.huru.ca/v1/client/$OS-$ARCH.sha256"
   # fallback (FW-CLIENT-BINARY-UNAVAILABLE): gh release download "$V" -R huru-io/lettuce -p "lettuce-$OS-$ARCH*"
   sha256sum --check "lettuce-$OS-$ARCH.sha256"   # macOS: shasum -a 256 --check …

A provisioned lettuce on PATH (or the fleet alias flt-issue, a symlink to the same binary) must report the same release in lettuce version; a mismatch warns FW-CLIENT-VERSION-SKEW on every command. When you see it, stop writing and run lettuce self-update (it replaces the binary from the server, verified), then lettuce status. The canonical recipe is SKILL.md §0.1 (lettuce skill).

2. Bind the store and its project — what .lettuce is decides the mode: a file is remote, a folder is a local in-repo store. The URL is the credential-only form (your token is the bare userinfo before @). Bind the project either in the URL path or on a project: line (do not state both and disagree — that is refused as ambiguous):

   https://<token>@api.lettuce.huru.ca/<projectname>
   # or
   https://<token>@api.lettuce.huru.ca/
   project: <projectname>

If you have no binding, discover the project with lettuce project list (no context needed) and pass --project / LETTUCE_PROJECT. If you cannot tell which project the work belongs to, ask the human/operator; never guess, and never create a project unasked. Your token also decides which domains (independent stores on one server) you reach: lettuce domain list, then --domain NAME / LETTUCE_DOMAIN / a domain: line in the pointer (precedence in that order, then the token's default; SKILL.md §0.2). In remote mode lettuce status names the server, domain and project you reached and where each came from.

3. Authenticate and identify yourself. Preferred, once enabled: your own Wordmade ID agent identity (bearer + LETTUCE_AUTH_MODE=wordmade-id). Fallback: a shared bearer token (a named token) a Huru human provides — keep it in LETTUCE_BEARER_FILE (or LETTUCE_BEARER), never in a committed pointer. In shared mode you MUST declare your own stable actor name (--author/LETTUCE_ACTOR, sent as X-Lettuce-Actor); never lettuce-operator. A long anonymous session must pick a name and keep it in its memory for the whole session and restarts. First time on a hosted project: lettuce author add <name> --idempotent, then link yourself with lettuce project author add <project> <name> --idempotent --author <name>. A writer token is enough for both. On a server with --auto-provision-actors, skip both and just write as --author <name> (SKILL.md §0.3 "First time on a hosted project").

4. Lease short (~3 hours). lettuce lease acquire <project>/<TASK> --author <you> --expires-at "$(date -u -d '+3 hours' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v+3H +%Y-%m-%dT%H:%M:%SZ)". A short lease lets another agent take over an expired or abandoned one (lease steal / re-acquire); hold longer work by renewing, never one long window.

Then continue below.

Move 0 — read the model, not the whole reference

The binary documents itself. Two commands, no store required:

lettuce skill      # the embedded agent guide (SKILL.md) — read this ONCE, top to bottom
lettuce docs       # the embedded wiki (HTML explorer); `docs show <page>` streams one page

lettuce skill prints the model-first guide — its opening frame:

…
# Using lettuce

`lettuce` is a work tracker **and coverage/quality store**. Canonical state
(projects, tasks, comments, runs, artifacts, cells) is held in a path-jailed
store; every mutation is validated and recorded as an event. ...
…

lettuce docs show <page> streams one wiki page as markdown (concepts and guides by slug), e.g. lettuce docs show concept-cell or lettuce docs show guide-first-contact. When prose and the binary disagree, the binary wins — so treat usage (below) as ground truth.

Move 1 — get the exhaustive contract on demand

You never guess a flag. For any command, ask the binary:

lettuce usage                      # every command, every flag, examples
lettuce usage cell set             # just one command's contract
lettuce usage cell set --format json   # machine metadata: kind, requires_root/project/author, flags, examples

The top of usage carries the Agent Guidance you should internalize before your first mutation:

## Agent Guidance

- Prefer --format json for automation. JSON and YAML outputs use stable machine
  envelopes with ok, data, warnings, and meta.
- Pass --project and --author explicitly for mutations. Do not infer project or
  author from the operating system, Git config, or store contents.
- Use fully qualified task references such as project/TASK-1 when project context
  might be ambiguous.
...

Two rules that will save you an hour: mutations need explicit --project and --author (lettuce never infers them), and task IDs need a 1–9 char uppercase prefix (LET-1, not t-1).

Move 2 — find out where you are

lettuce status --root .lettuce --format plain

root=/repo/.lettuce mode=filesystem project= author= initialized=true diagnostics=0

initialized=true diagnostics=0 means a healthy store already exists at .lettuce. initialized=false means there is no store yet — jump to the Project setup playbook to stand one up. If diagnostics is non-zero, run lettuce doctor --format json for the diagnosis and repair suggestions before touching anything.

The store root resolves through --root, then LETTUCE_ROOT, then config; in a repo the convention is a git-tracked .lettuce/.

Move 3 — see the shipped convention (the default is 88 dimensions)

Coverage grading runs on the one convention-as-data lettuce ships — bundled in the binary and active on every project by default, with nothing to enable. Read a project's effective dimensions (this needs a store root and --project):

lettuce dimension list --root .lettuce --project <P> --format plain # this project's EFFECTIVE dimensions

project    : <P>
pack       : coverage
dimensions:
  ID           SLUG  NAME                     FAMILY        …
  coverage-a   A     Functional correctness   correctness   …
  coverage-b   B     UX / DX (usability)      usability     …
  coverage-h   H     HTTP / API surface       interface     …
  …
count      : 88

The shipped default is coverage — lettuce's own 88-dimension quality taxonomy across 15 families, each dimension carrying a full methodology (Procedure / Best practices / Tools / Current approaches / Evaluation / Hardened). The pack: coverage line is the convention's internal identifier surfacing in the envelope — not a command you run. A dimension's slug is its coverage letter (A, B, H, …); read one axis in full with:

lettuce dimension show A --root .lettuce --project <P> --format json  # one axis + its methodology

Its state ladder is untested → planned → in_progress → gap → evidence_linked → smoke → hardened (plus blocked/regressed flagged and excluded/waived out-of-denominator); hardened is reached only through the guard-bite gate — a committed check that provably bites under fault-injection.

Add your own axis. On top of the shipped convention you can declare a project-specific dimension (strictly additive — it can never shadow the convention's vocabulary):

• lettuce dimension declare <slug> --family <F> --applicability universal|conditional --project <P> --author <A> adds a project axis. See Dimensions.
• To tune the ladder / gates / DoD for one project without authoring a new convention, use the defaults layer (covered in the setup playbook).

Move 4 — ask the store what to do next

If cells have been asserted, one command orients you and hands you a target:

lettuce board next --root .lettuce --project <P> --format plain

For the coordination picture — who is working, what needs help, what is available — use the single global view:

lettuce work --root .lettuce --project <P> --format plain

lettuce work composes the tasks and leases: IN FLIGHT (holder + expiry + last event), NEEDS HELP (blocked/needs-human or a stale expired lease), and AVAILABLE (no active lease). To find available work directly, lettuce task list --unleased; to take over stalled work, lettuce lease list --status expired then lettuce lease steal.

On an empty store this is honest, not an error:

board next · project <P> · 0 open cell(s)
  no cells defined yet — this project is UNSCOPED, not complete. Nothing has been assessed.
…

Once there is coverage, board next ranks every scope weakest-first, prints a single start here pointer, and — if a Definition of Done is declared — leads with the DoD verdict line:

board next · project webapp · DoD: NOT DONE (1/2 scopes met) · 1 open cell(s)
  DoD bar: hardened
  ...
start here: auth / dim=a;scope=auth;unit=login  [Planned · Functional correctness]
  ...
  ↳ detail: lettuce cell show "dim=a;scope=auth;unit=login" --project webapp
…

Every summarized line prints the exact lettuce … command to descend, so you are never stuck. --depth 0|1|2 deepens the report; --scope <name> restricts it to one scope.

You are now oriented — what to do with it

1. Read the DoD verdict first (lettuce dod show --project <P>), then take the single target board next hands you — don't hand-compose a coordinate. 2. Discover concrete work with lettuce task list --project <P> and lettuce query run … (FQL). 3. Drive the loop: claim a lease, transition status, do the work, record evidence, grade the cell. The full worked example is the Agentic loop demo.

See also

• Project setup playbook — prepare a project from scratch.
• Agentic loop demo · Agentic cycles · How to read a store
• Getting started · Overview · Command Reference

The first thing an agent does with an unfamiliar store is not act — it reads. lettuce is built so the store read forward is a plan and read backward is proof, and every reading surface is a pure, deterministic projection that never mutates. This guide is the orientation pass: what to read, in what order, and how to interpret the verdict.

The one-command orient: board next

Start here. board next distills the whole coverage board into an agent-facing orientation report — "what should I harden next?" — without exporting and re-parsing anything:

lettuce board next --project P --format json          # meters + start-here
lettuce board next --project P --depth 2 --format json # + weakest units + concrete coords

• It is a pure read over the same BoardExport that board export/render produce: a project context is required — resolved from --project, else LETTUCE_PROJECT, else project: in config (an empty value counts as MISSING, not malformed — the resolver skips it, so an empty --project and no flag at all reach the same refusal) — and a MISSING context is refused FW-CMD-MISSING-PROJECT-CONTEXT while an INVALID name is refused FW-NAME-PROJECT (LET-264 split them). It reads only that project's board, never a cross-project scan.
• Output is weakest-first: every scope's meter ranked, plus a single "start here" pointer (the globally weakest open cell).
• --depth deepens detail: 0 (default) meters + start-here; 1 adds each scope's shape-aware subcounts; 2 adds the weakest units and the concrete gap/untested coordinates — each capped with an honest +N-more drill string, never a silent truncation.
• --scope <slug> restricts the report; a slug that names no scope on the board is refused with the available list.

The frontier is the not-done, not-excluded, not-smoke cells (gap + untested). An empty board is not an error — every scope meter reads n/a. The report is self-guiding: each summarized node prints the exact lettuce … command to descend, so you are never stuck.

Reading the DoD verdict line

If the project has declared a Definition of Done, board next leads with it — the first line is the verdict:

DoD: NOT DONE (0/1 scopes met)

Read this first, before picking any target. The verdict is a strict per-scope AND-gate over applicable (non-excluded) cells — a scope is done only when every cell clears the bar, reported as a k/n count, never a blended percentage. Two consequences to internalize:

• 100% hardened can still be NOT DONE. Setting a DoD never moves the hardened ratio; a scope may read fully hardened yet be unmet because its evidence is stale or too shallow (depth/recency floors).
• Outer gates apply. Beyond per-scope coverage, overall DONE also requires every committed milestone reached and zero non-terminal tickets — visible via lettuce dod show as milestone_gate and ticket_gate.

A project that declared no floor reports declared=false and the board renders unchanged (DoD is opt-in).

The three freshness/depth/dod axes

The cells query source carries the DoD-derived axes that explain why a cell is or isn't done — the vocabulary the verdict is computed from:

| Axis | Values | Meaning | |---|---|---| | freshness | fresh | aging | stale | how current the cell's evidence is | | depth | int | distinct-revision confirmation count (FRESH-2) | | dod | blocking | met | is this cell blocking the Definition of Done | | dod-reason | grade | depth | recency | unknown | why a blocking cell blocks |

Reading these turns "what is not yet done?" into a precise query rather than a guess.

Querying with FQL over tasks, cells, and events

FQL reads the store deterministically: from SOURCE [where EXPR] [select f1,f2] [order by f [desc]] [limit N]. Strings use double quotes (single quotes are rejected).

# Work plane — what is in flight.
lettuce query run 'from tasks where status = active select task,title' --project P --format json
lettuce query tasks --group-by status --project P --format json        # bucketed counts

# Coverage plane — what remains, by axis.
lettuce query run 'from cells where dod = blocking select coordinate,state' --project P --format json
lettuce query run 'from cells where freshness = stale select coordinate'  --project P --format json
lettuce query run 'from cells where depth >= 2 select coordinate'         --project P --format json
lettuce query run 'from cells where dod-reason = grade select coordinate' --project P --format json

FQL has no dedicated scope/unit filter operator — slice by a coordinate member instead: where coordinate contains "scope=login". See scopes. Sources include tasks, events, cells, registry, authors, projects, dimensions; the cells source lists stored assertions only — sparse pack-defaults are never rows. Soft-archived tasks are hidden everywhere by default (--include-archived opts in).

Reading one object: task show and task audit

lettuce task show P/TASK-1 --with-body --format json   # or --full
lettuce task audit P/TASK-1 --format json              # full event history

Every mutation is an event, so task audit is the object's complete provenance — who did what, when, with which reason. Bodies are versioned, never edited in place, so the history is faithful.

Rollups and timelines — the aggregate reads

lettuce cell rollup --by test-coverage --project P --format json   # per-member floor + hardened ratio
lettuce query timeline --project P --kind object-created --format json
lettuce query timeline --project P --task P/TASK-1 --format json

• cell rollup --by DIM pools a project's stored cells by one dimension: the floor (least-progressed) state, hardened count, non-excluded denominator, and ratio per observed member — N/A-excluded, never blended. This is where you see which axis is weakest before drilling with board next.
• query timeline merges events chronologically, filterable by --task, --author, --kind, --since, --until — the history of the whole project or one object.

How an agent orients before acting

A disciplined orientation pass, in order:

1. Verdict — board next (reads the DoD: … line first): are we done, and what's blocking? 2. Frontier — the same report's weakest scope + start-here coordinate: where is the next target. 3. In-flight work — query tasks --status active and your held leases (lease list --holder <you>): what is already claimed, so you don't collide. 4. Provenance, if needed — task audit / query timeline on the target: why the cell is in its current state.

Only then act. The store, not your context, is your memory — read it first every cycle. See running lettuce in autonomous agentic cycles for the full orient → act → reflect → file loop.

Read machine-first: --format json

For any automated reader, pass --format json (or yaml). Every result is the stable envelope { ok, data, warnings, meta }; errors are { ok:false, error:{ code, message, diagnostics:[...] } } with machine-readable codes. Branch on the code, not the message text — diagnostics carry expected/actual, repairability, and suggested_actions, so the error tells you the fix. Exit codes are distinct too: 1 invalid input, 2 not found, 3 expected-revision mismatch, 6 interrupted operation requires recovery, 0 success.

See also

• Querying with FQL · Cells — the coverage model
• Scopes · Milestones & DoD
• Running lettuce in autonomous agentic cycles · Configuring lettuce for leverage

A retry is only safe if the second attempt can tell it is a second attempt. An agent whose network call times out does not know whether the mutation landed, and re-running it blind is how one intended task becomes two.

--idempotency-key closes that gap: the first call performs the mutation and remembers its response; a repeat of the same call with the same key returns that stored response instead of mutating again.

lettuce task create DEMO-1 --project demo --author agent-1 \
  --title "Wire the importer" --idempotency-key run-42-create-demo-1
lettuce task create DEMO-1 --project demo --author agent-1 \
  --title "Wire the importer" --idempotency-key run-42-create-demo-1   ->  ok: true   the replay

A replay says so, in meta

This is the part worth wiring into a caller. The replay returns the original response — including the same operation_id — and marks itself:

first call    ok=true   operation_id=op-20260827-171309-067f48d57b6ddb4
replay        ok=true   operation_id=op-20260827-171309-067f48d57b6ddb4
                        meta.idempotency_replayed = true

So a caller distinguishes "my retry worked" from "my retry was a no-op because the first attempt had already succeeded" by reading meta.idempotency_replayed, not by comparing timestamps or diffing the store.

Reusing a key for a different mutation is refused

A key identifies one specific mutation, not a session or a batch. Reuse it with a different payload and lettuce refuses rather than guessing which one you meant:

lettuce task create DEMO-1 --title "Wire the importer" --idempotency-key k1   ->  ok: true
lettuce task create DEMO-1 --title "Something else"    --idempotency-key k1   ->  FW-CMD-IDEMPOTENCY-CONFLICT: idempotency key was already used with a different mutation scope

The output format is not part of the mutation (LET-1867). The record is the JSON envelope whatever --format the first call used, and a replay renders it in the replay's own format — a first call in table and a retry in json get the same result, the json one with meta.idempotency_replayed = true. (Before v0.20.1 the format was part of the identity locally, and such a retry was refused with this code; over --server-url it never was.) A human replay does not repeat the first call's warnings on stderr; the json/yaml envelope still carries them.

There is a second form of the same code: idempotency key is already in progress, raised when another call holds the same key and has not completed. The mismatched-scope form is a bug in the caller and retrying will never help. Read the message, not just the code — they share it.

For the in-progress form, the suggested actions follow the claimant recorded on the claim (its host and pid):

| claimant | what the refusal tells you | |---|---| | still running on this host | retry with the same key shortly; the retry replays its response | | gone (process no longer exists) | the claim is orphaned: run lettuce recover, which completes it from its cached response (or reclaims it if none was written), then retry | | cannot be verified (another host, no recorded pid, or a pid owned by another user) | retry later if it may still be running; once you have confirmed it is gone, lettuce recover --abandon reclaims it — otherwise it lasts until its TTL, or forever without one |

lettuce doctor lists every such orphaned claim as FW-RUNTIME-IDEMPOTENCY-ORPHANED.

Only mutation commands accept it

The flag is refused, rather than silently ignored, on commands that do not support it:

lettuce doctor --idempotency-key k9   ->  FW-CMD-USAGE: idempotency key is not supported for this command yet

Supported today: init; author add; project create, project author add; task create/set/unset/set-list/transition/body; version add; comment add/edit/status; lease acquire/renew/steal/release; run start/finish/log/summary; artifact add/replace; registry create/update; custom set/clear; and the milestone wrappers over registry. The command reference marks each command with idempotency key: true, which is the authoritative list — the enumeration above is a convenience and can age.

The record is runtime-only, and expires

The stored response lives under .runtime/idempotency/<key-hash>/ in the store directory — alongside a scope-hash (what the key was used for) and an expires-at. Two consequences worth knowing:

• It does not travel with the store. .runtime/ is git-ignored and carries no tracked files, so a clone, an export or a fresh checkout starts with no idempotency history. A key that replayed on one machine will perform the mutation on another.
• It expires after 24 hours. Past that, the same key is a fresh key and the mutation runs again. Idempotency here protects a retry loop, not a permanent record of "this was already done" — the store's own state is that record.

Choosing keys

Derive the key from the work, not from the clock: something like <run-id>-<step>-<target> is stable across a retry of the same step, which is exactly when you need it to match. A key containing a timestamp defeats the mechanism, because the retry generates a different one.

See also

• Driving lettuce from a file: structured external input — the other half of automating mutations; note that idempotency_key is a denied envelope key and stays on the command line.
• Running lettuce in autonomous agentic cycles — the loop this flag exists to make re-runnable.

This is the do-this-now guide for turning a repository into a project lettuce can steer. By the end you have a store, a coverage model that fits your project, an evaluable Definition of Done, and the discipline to keep it honest.

Everything here is real — run each command. It builds on the concepts (Scopes, Dimensions, Cells, Milestones & DoD) for the what; this page supplies the how. New to lettuce? Read First contact first.

1. Init & bootstrap (store, project, author)

One idempotent command creates the store skeleton, a project, and your author:

ROOT=.lettuce; P=webapp; A=codex-01
lettuce init --root "$ROOT" --author "$A" \
  --bootstrap-project "$P" --bootstrap-author --idempotent --format plain

initialized /repo/.lettuce

Confirm health before anything else:

lettuce status --root "$ROOT" --format plain
# root=/repo/.lettuce mode=filesystem project= author= initialized=true diagnostics=0

Attribution discipline from command one: lettuce never infers --project or --author from the OS, Git, or store contents — pass both explicitly on every mutation. Pick a stable, non-secret author id (codex-01, ci-agent). Track .lettuce/ in git so the store travels with the repo (only .lettuce/.runtime/ is ignored). For tuning the client context (default root, mode, format), see Configuring lettuce for leverage.

2. The working model (the coverage convention)

Coverage grading runs on the one convention-as-data lettuce ships. The shipped default is coverage (lettuce's 88-dimension quality taxonomy across 15 families), and every project runs it by default — nothing to enable or choose.

The coverage convention ships 88 dimensions across 15 families, each carrying a full methodology (Procedure / Best practices / Tools / Current approaches / Evaluation / Hardened). Inspect it per project (needs a store root and --project):

lettuce dimension list  --root "$ROOT" --project "$P" --format json   # every dim + its methodology
lettuce dimension show A --root "$ROOT" --project "$P" --format json  # one axis in full

Its ladder is untested → planned → in_progress → gap → evidence_linked → smoke → hardened (plan, start, flag-gap, exercise/exercise-gap, link-evidence, harden [guard-bite gated], exclude/waive, block, regress).

> For the same convention with one project-specific adjustment (an extra > working state, an added edge or guard) you don't need another pack — record a > per-project tweak with the defaults layer.

3. Design YOUR scopes (a decision procedure, not a template)

A scope is a partition of the board scored separately and never blended — blending hides gaps. lettuce ships four scope archetypes as reference examples, not a mandatory template:

| Archetype | Shape | Row axis | Good for | |---|---|---|---| | s1 Feature | grid | a feature/command (unit=) | user-facing features × quality dims | | s2 Component | grid | a subsystem (unit=) | internal modules × quality dims | | s3 Product | scalars | none (rows are the dims) | one grade per whole-product axis | | s4 Ecosystem | ladder | a milestone | staged bets that mature over time |

The slugs s1–s4 are magic: they carry those built-in shapes. Any other scope name (scope=auth, scope=checkout) is legal and gets a default heatmap shape. Do not force your project into s1–s4. Instead:

The decision procedure. 1. Enumerate the real surfaces of work that need independent coverage — the things you would not want averaged together (e.g. auth, checkout, api, data-migration). Each becomes one scope. 2. Pick a shape per surface. A grid of units × dimensions? Reuse the s1/s2 archetype. One grade per axis for the whole product? s3. A staged hypothesis that matures (sellable, GA)? s4 + milestones. A flat set of items? use a named scope (heatmap). 3. Define "done" per scope — the grade floor each must reach (§5). 4. Keep scopes few and orthogonal. If two scopes always move together, they are one scope.

A named-scope board needs nothing but cells that carry a scope= member:

lettuce cell set "scope=auth;unit=login;dim=input-validation" --state in_progress \
  --root "$ROOT" --project "$P" --author "$A" --format plain
lettuce cell set "scope=checkout;unit=cart;dim=test-coverage" --state planned \
  --root "$ROOT" --project "$P" --author "$A" --format plain

To get the richer archetype shapes (grid/scalars/ladder) and real row names, declare scope/unit as dimensions and use the magic slugs — see the worked recipe in lettuce skill ("Standing up a coverage board from scratch"):

lettuce dimension declare scope --family interface --applicability universal \
  --name "Scope" --root "$ROOT" --project "$P" --author "$A" --format plain
lettuce dimension member add scope s2 --name "Component" \
  --root "$ROOT" --project "$P" --author "$A" --format plain
lettuce dimension declare unit --family interface --applicability universal \
  --name "Command / unit" --root "$ROOT" --project "$P" --author "$A" --format plain
lettuce dimension member add unit store --name "store" \
  --root "$ROOT" --project "$P" --author "$A" --format plain
# an S2 component-grid cell (has a unit row):
lettuce cell set "dim=am;scope=s2;unit=store" --state gap --reason "durability not yet proven" \
  --root "$ROOT" --project "$P" --author "$A" --format plain

> A cell that declares no scope= is bucketed under the reserved unscoped > scope at evaluation — never silently outside the DoD frame. scope=unscoped > is refused (FW-NAME-RESERVED).

4. Units & dimensions per scope

4a. Pick from the shipped palette

Each cell grades a unit (a row: a command, a subsystem) along a dimension (a quality axis). Start from the active pack's dimensions as a palette:

lettuce dimension list --root "$ROOT" --project "$P" --format plain   # this project's EFFECTIVE set
lettuce dimension show A --root "$ROOT" --project "$P" --format plain  # one axis in full

Read a dimension's methodology before grading any of its cells — it is what separates a shallow smoke grade from a hardened one. For coverage dim D (Data integrity):

Procedure: exercise the write path; assert ATOMICITY (write-temp-then-atomic-
  rename or a WAL) and DURABILITY (fsync the file AND its parent dir before ack);
  inject a torn/partial write (crash mid-write, truncated temp, kill -9) and assert
  the store stays consistent + read-back returns the exact bytes. Then name the
  isolation level and prove the anomalies it forbids don't occur.
Best practices: make the ACID story EXPLICIT; writes are write-temp-then-atomic-
  rename never in-place; never ack before durable; "validated but never persisted"
  is a real bug class, so read the canonical file back and assert exact bytes.
Tools: atomic rename(2), fsync/fdatasync + directory fsync, WAL engines (SQLite
  WAL, LMDB, BoltDB); Jepsen elle for isolation; ALICE/CrashMonkey crash injection.
Current approaches: MVCC + snapshot isolation as the default; serializable via SSI;
  elle infers isolation anomalies from histories; deterministic simulation.
Evaluation: atomicity (no torn write survives a crash); durability (an fsync'd
  write survives power loss); isolation (forbidden anomalies never observed);
  multi-object atomicity (a reader never sees a partial commit).
Hardened: a committed torn/partial-write guard bites (green → break → RED → green)
  if atomicity/durability is removed; layer an isolation guard + a fsync-durability
  guard. Distinct lens vs F (F = in-process race-safety; D = the store's contract).

4b. Ideate a custom dimension (with its methodology)

When your project's nature needs an axis no pack ships, declare one. It is strictly additive — it can add axes and members but never shadow pack vocabulary. Ideate it in four parts:

1. Name the risk — the failure this axis guards against (e.g. "a schema migration corrupts or loses data under partial failure"). 2. Pass criterion — what "covered" means (migrations reversible + loss-free under injected partial failure). 3. Methodology — the procedure an agent follows to grade a unit on it (Procedure / Best practices / Tools / Current approaches / Evaluation / Hardened), so the axis is gradeable, not decorative. 4. Hardened-evidence bar — what a bite-proven guard must do.

Declare it (--family must be one of the active pack's families):

lettuce dimension declare data-migration --family reliability --applicability conditional \
  --name "Data migration safety" \
  --description "Schema/data migrations are reversible and loss-free under partial failure." \
  --root "$ROOT" --project "$P" --author "$A" --format plain
# dimension declare ok
lettuce dimension show data-migration --root "$ROOT" --project "$P" --format plain

Add first-class members if the axis enumerates values:

lettuce dimension member add data-migration forward --name "Forward migration" --rank 10 \
  --root "$ROOT" --project "$P" --author "$A" --format plain
# dimension member add ok

> Honest limitation (current build): dimension declare persists a one-line > description but has no methodology field — only shipped pack > dimensions carry the structured six-facet (Procedure / Best practices / Tools / > Current approaches / Evaluation / Hardened) text. So write your > custom dimension's full methodology somewhere durable anyway (a project doc, > a pinned cell note, or the proving task's body), because a dimension without > a methodology is incomplete. For a methodology that travels with the binary, > prefer a coverage-pack dimension or contribute your axis + methodology to a > pack. Do not assert grades on an axis whose methodology you have not written > down.

5. A Definition of Done that's actually evaluable

Turn "done" from an assertion into a measurement. Represent the plan as milestones + tickets, then declare the grade floor so board next can compute a verdict.

# Frame outcomes as milestones (the hypothesis ladder / S4 rungs).
lettuce milestone create v1-launch --title "v1 launch" \
  --root "$ROOT" --project "$P" --author "$A" --format plain
lettuce milestone list --root "$ROOT" --project "$P" --format plain
# webapp/milestone/v1-launch

# Declare the bar: the minimum grade every cell must reach to count as done.
lettuce dod set --grade hardened --root "$ROOT" --project "$P" --author "$A" --format plain
# dod set ok  (add --depth N / --recency for confirmation-depth + freshness floors,
#              or --scope S to override one scope's floor)

Now the DoD is a live verdict — a strict per-scope AND-gate plus outer milestone and ticket gates:

lettuce dod show --root "$ROOT" --project "$P" --format plain

project  : webapp
declared : true
grade    : hardened
verdict:
  coverage_met   : false
  met_scopes     : 0
  milestone_gate:
    met     : false
    reached : 0
    total   : 1
  scopes:
    APPLICABLE  BLOCKED_GRADE  MET  SCOPE     VERDICT
    2           1              1    auth      unmet
    1           1              0    checkout  unmet
  ticket_gate:
    met   : false
    open  : 1
    total : 1
  total_scopes   : 2
  verdict        : unmet

How tickets map to units. A cell is the address of work; a task is the work. The disciplined loop is: board next names a weak cell → you create a ticket to fix it → link that finished ticket as the cell's evidence → the guard-bite gate then authorizes harden. DoD's ticket_gate refuses "done" while any ticket is still open, and milestone_gate refuses it until every committed milestone is reached — so the verdict reflects both proven coverage and closed work. The full closing loop is the Agentic loop demo.

6. Hygiene & discipline — the per-cycle checklist

The map only steers if it stays truthful. Every cycle:

• [ ] Orient from board next, take its target. Don't hand-pick coordinates; act on the one the store surfaces (weakest scope, weakest cell first).
• [ ] Read the dimension's methodology before grading any cell on it.
• [ ] Flip cells with cell transition (gated), never cell set --state hardened. cell set asserts a state directly and bypasses the guard-bite gate — an unproven green. Use cell set only for planned / blocked / waived / seeding. Reach hardened through the gated transition with a real proving task linked as evidence.
• [ ] One ticket per finding. Discover a defect mid-work? File it as its own cell (cell set --state gap/planned) + ticket so the next ORIENT sees it.
• [ ] Never --facilitate past a failed gate to "make progress" — one unproven green poisons every future orientation.
• [ ] Keep the board and tickets current — close tickets, harden cells, and let cell reconcile machine-regress stale greens whose evidence unresolved.
• [ ] Validate after structural work — lettuce validate --strict and lettuce doctor --format json after import/repair/conflict resolution.
• [ ] Re-orient. Run board next again; confirm the frontier moved for a real reason (a hardened cell, a filed finding), not drift.

See also

• First contact · Agentic loop demo · Agentic cycles
• Configuring lettuce for leverage · How to read a store
• Scopes · Dimensions · Cells · Milestones & DoD · Packs
• Cells — Commands · Definition of Done — Commands

The same binary that is a CLI is also an HTTP server: lettuce serve exposes the store over HTTP so the identical CLI, pointed at it in client mode, can drive it remotely. Exposing a store to the network is a security decision, and lettuce is built fail-closed so the unsafe path is the one you have to opt into explicitly.

The fail-closed model (ADR-0008)

lettuce serve --root . --listen 127.0.0.1:8727      # safe default: loopback only

The default listen address is 127.0.0.1:8727 — loopback only, reachable solely from the same host. The invariant:

> A non-loopback --listen with no shared secret and no --tokens-file refuses to start.

A secret can come from any of --secret, --secret-file, LETTUCE_API_SECRET, or LETTUCE_API_SECRET_FILE. If none is present and you bind to a non-loopback address, startup refuses unless you pass --allow-unauthenticated-nonloopback — and even then startup warns. You cannot accidentally serve an unauthenticated store to the network; you have to state the override in words.

The serve surface

serve is kind: server — it requires a root but neither a project nor an author (those arrive per-request). Its flags:

| Flag | Env | Purpose | |---|---|---| | --listen ADDR | LETTUCE_LISTEN | Listen address (default 127.0.0.1:8727; non-loopback requires a secret) | | --secret SECRET / --secret-file PATH | LETTUCE_API_SECRET (_FILE) | The bearer token secret | | --allow-ip IP-OR-CIDR | LETTUCE_ALLOWED_IPS | Allowed client IP/CIDR (repeatable) | | --trusted-proxy-cidr IP-OR-CIDR | — | Bounded trusted proxy source range (repeatable; /0 is refused) | | --rate-ip-rpm RPM | LETTUCE_RATE_IP_RPM | Per-IP requests/minute (ADR default 600) | | --rate-actor-mutation-rpm RPM | LETTUCE_RATE_ACTOR_MUTATION_RPM | Per-actor mutating requests/minute (default 300) | | --rate-global-mutation-rpm RPM | LETTUCE_RATE_GLOBAL_MUTATION_RPM | Global mutations/minute across all actors (default 60) | | --rate-burst N | LETTUCE_RATE_BURST | Per-IP burst: max requests in a 1s window (default 60) | | --rate-limit RPM | LETTUCE_RATE_LIMIT | Legacy per-IP limit (seeds --rate-ip-rpm) | | --authz-policy PATH | LETTUCE_AUTHZ_POLICY_FILE | Authorization policy JSON file | | --auth-subject SUBJECT | — | Authenticated subject name of the legacy shared secret | | --domains-root BASE | LETTUCE_DOMAINS_ROOT | Serve several independent stores ("domains"), one per initialized folder BASE/<name> | | --tokens-file PATH | LETTUCE_TOKENS_FILE | Named bearer tokens, each its own subject with its own domains and default domain (secrets never inline) | | --auto-provision-actors | LETTUCE_AUTO_PROVISION_ACTORS | Create missing X-Lettuce-Actor authors for authorized mutations | | --allow-unauthenticated-nonloopback | — | Explicitly permit a non-loopback listener WITHOUT a secret (warns) | | --recover-on-start | LETTUCE_RECOVER_ON_START | Filesystem: reclaim only a provably dead local writer. Dedicated-git: first run recover (re-commits acknowledged operations whose durable commit failed), then discard only the remaining unattributed torn state under the sole-writer assertion. Startup is refused (FW-RUNTIME-RECOVERY-FAILED, nothing discarded) while an acknowledged operation is still uncommitted or a non-store file (e.g. a serve.log inside the store root) is in the worktree. | | --push-interval DURATION | LETTUCE_PUSH_INTERVAL | Auto-push to git remote at interval (dedicated-git only) |

Endpoints

GET / and GET /SKILL.md serve the embedded agent guide unauthenticated — this is intentional: the guide is public documentation, not store data (so are /docs, /docs/flat.md and the /v1/health liveness probe). The store API lives under /v1/… (for example, DELETE /v1/projects/{project}/dod clears a Definition of Done) and is what the bearer credential protects. The authenticated GET /v1/version reports the server's release, and every authenticated response carries it in X-Lettuce-Server-Version, so agents pin a matching client (SKILL.md §0.1). The server's own client binaries (GET /v1/client/{os}-{arch} and .sha256, LET-1932) need the bearer but no role: any token may download them, which is what lets lettuce self-update work with nothing but a token. They are the release's public-to-token-holders build artifacts, never store data. The admin-only GET /v1/clients names which token subjects and actors run which client release; serve --min-client-version (off by default) refuses mutations from older released clients.

Auth and identity posture

lettuce serve does have an auth mechanism — a bearer model plus a per-actor identity header:

• Bearer credential (authentication). Either the legacy --secret (one shared bearer, one subject, reaches only the default domain) or named tokens from --tokens-file (each its own subject, with its own reachable domains and default domain — docs/operations/API-DOMAINS.md). Clients present it as --bearer / LETTUCE_BEARER (_FILE) or embedded in the store URL. Requests to /v1/… without a valid bearer are rejected. Neither is a per-user identity.
• Actor identity (attribution). A client also sends its acting author via the X-Lettuce-Actor header (LETTUCE_ACTOR in client mode). Because mutations must be attributed, an unknown actor is refused unless --auto-provision-actors is set (which creates the missing author for authorized mutations).
• Authorization policy (optional). --authz-policy PATH points at an authorization policy JSON file, with --auth-subject naming the authenticated subject. The sources describe the flags but not the schema/contents of that policy file — treat the policy format as a binary detail to read from lettuce usage serve and the shipped spec, not something to guess at here.

Who may register authors and manage membership (LET-1885)

Under an authz policy a per-person writer token lets that person's agents onboard themselves; they do not need an admin:

register your OWN acting name        lettuce author add <you> --idempotent                   writer
link your OWN name to a project      lettuce project author add P <you> --author <you>       writer
  (+ --bootstrap-author registers your own name in the same call)                          writer
link another REGISTERED author, as a member of P                                           writer
link another author as a NON-member  refused FW-CMD-MISSING-AUTHOR for every role: join first
register ANOTHER name                author add <other>, or --bootstrap-author for another   admin
author deactivate / reactivate, remove a member (no unlink command)                        admin

The authoritative copy is docs/guides/SERVER-SECURITY.md ("Who may register authors and manage membership"); the HTTP spec's "Author and membership routes" table is the route list, and a test keeps it equal to the code.

> Honest gap: the gold sources describe the transport as plain HTTP and > document no built-in TLS termination. For any remote exposure, terminate TLS at a > trusted fronting proxy — the --trusted-proxy-cidr flag exists precisely to name > that proxy's source range so client-IP allowlisting still works behind it. Do not > assume the served port encrypts traffic on its own; the sources do not claim it.

Rate limiting (ADR-0003)

Four independent gates bound abuse, each with an ADR default: per-IP requests (--rate-ip-rpm, 600), per-actor mutations (--rate-actor-mutation-rpm, 300), global mutations (--rate-global-mutation-rpm, 60), and per-IP burst (--rate-burst, 60 in a 1s window). The legacy --rate-limit seeds the per-IP gate. Tighten these below the defaults for a public-facing instance. Burst refusals do not spend per-minute IP tokens. Route, actor, and JSON refusals do not spend mutation tokens; only an admitted mutation attempt does. The admission decision is shared by idempotent and non-idempotent mutations and is charged once per request.

With --recover-on-start, filesystem mode never force-clears a live, cross-host, or unreadable writer lock. The server reports that unresolved condition both on stderr and in machine output warnings[]; it must not call an unresolved store auto-healed.

In dedicated-git mode the order is recover FIRST, reset SECOND (LET-448). A mutation whose durable commit failed was still acknowledged to its client (ok:true with an FW-GIT-COMMIT-FAILED warning), so uncommitted state at boot is not automatically a torn partial. Recover re-commits every canonical operation it can attribute; only what is left is discarded back to HEAD. If recover itself fails, nothing is discarded and mutations stay fail-closed on FW-GIT-DIRTY until an operator runs lettuce recover.

Local vs remote exposure

| Exposure | How | Posture | |---|---|---| | Loopback (default) | --listen 127.0.0.1:8727 | Same-host only. No secret required; safe for a local agent driving its own store over HTTP. | | Trusted LAN | non-loopback --listen + secret + --allow-ip CIDR | Secret mandatory (fail-closed). Restrict clients with IP allowlists. | | Public / remote | non-loopback + secret + allowlist + TLS-terminating proxy + tight rate gates | Every guard on. Front with a proxy for TLS (see honest gap above); name it with --trusted-proxy-cidr. |

Never reach for --allow-unauthenticated-nonloopback on anything beyond a fully trusted, isolated network — it is the deliberate override of the whole fail-closed model, and startup warns for a reason.

Driving a served instance (client mode)

Point the identical CLI at the server instead of mounting the store:

export LETTUCE_SERVER_URL=https://lettuce.example:8727   # or --server-url
export LETTUCE_BEARER_FILE=/run/secrets/lettuce-bearer   # or --bearer
export LETTUCE_ACTOR=agent-1                             # X-Lettuce-Actor identity
# For an organization-gated service, configure the pair together:
export LETTUCE_ORGANIZATION=huru
export LETTUCE_ORGANIZATION_TOKEN_FILE=/run/secrets/lettuce-organization/token
lettuce task list --project P --format json              # dispatched over HTTP

LETTUCE_SERVER_URL is overridden by a discoverable repo-local .lettuce: if the working directory (or an ancestor) holds a .lettuce, that store answers and the env is ignored. Run these commands where no .lettuce is in scope, or pass the --server-url flag — which always wins over a repo-local .lettuce — to force client mode regardless.

The organization token is an additional admission boundary, not an agent identity. In Wordmade ID mode, LETTUCE_BEARER[_FILE] carries each agent's own OAuth token and the server derives the actor from its verified UUID.

Almost every command works over the HTTP client — the authoritative per-command answer is the kind field of lettuce usage <cmd> --format json. The narrow exceptions are refused in client mode: serve itself, sync status/push/pull, and github init-repo (they act on a local process or the local working copy + Git remote), plus the bulk/confirmation cell ops (cell set-where, clear-where, verify, affirm, local import) which are local / dedicated-git only.

What is and isn't safe to expose

• Safe by default: loopback serve for a co-located agent; the / and /SKILL.md guide endpoints (public docs by design).
• Safe with the guards on: non-loopback serve with a secret, an IP allowlist, tuned rate gates, and TLS terminated at a trusted proxy.
• Not safe: any non-loopback listener without a secret. lettuce refuses it unless you explicitly override — take the refusal as the correct answer rather than reaching for the override.

See also

• The store and the two data planes · Server & GitHub — Commands
• Configuring lettuce for leverage (modes, config precedence, --config)
• How to read an existing store

Most commands take their fields as flags. When the values come from another program — a generator, a form, an agent assembling a task body — putting them on a command line means quoting prose into a shell, and that is where multi-line bodies and apostrophes go wrong.

--from-json and --from-yaml take those fields from a file instead. The command is still named on the command line; only its field values move into the envelope.

The wrapper is required

Both flags accept the same envelope. The wrapper is not optional and not inferred — a bare object of fields is refused.

schema_version: v0.16
kind: lettuce-command-input
data:
  task_id: DEMO-1
  title: Wire the importer
  body: |
    Multi-line prose, apostrophes, "quotes" — none of it touches a shell.

{"schema_version":"v0.16","kind":"lettuce-command-input",
 "data":{"task_id":"DEMO-1","title":"Wire the importer","body":"..."}}

lettuce task create --project demo --author agent-1 --from-yaml ./new-task.yml   ->  ok: true

A wrong schema_version is refused FW-CMD-USAGE (unsupported external input schema_version), and only schema_version, kind and data are accepted at the top level.

Not every command accepts an envelope

The support check runs before the file is parsed, so a command that does not accept external input tells you that plainly instead of complaining about your file:

lettuce doctor --from-yaml ./anything.yml   ->  FW-CMD-USAGE: --from-yaml is not supported for this command

That ordering matters when you are debugging: a message about the file means the command was accepted and the payload is the problem.

The envelope cannot set your execution context

data may carry a command's own fields. It may not carry the trusted context or anything credential-shaped — root, project, author, config, format, mode, bearer, token, PATs, listen addresses and proxy/rate settings are all refused:

lettuce task create --from-json ./new-task.json   ->  FW-CMD-CONTEXT-IN-EXTERNAL-INPUT: external input cannot set trusted execution context

This is deliberate. A file you received decides what to record; it never decides which store it lands in, who it is attributed to, or what credentials are used. Those stay on the command line, where the operator sets them. The scan is recursive, so a denied key nested deep in the payload is caught too.

CLI flags win; the envelope fills the gaps

The two sources compose rather than conflict, and the rule is one-directional:

> A value supplied on the command line always wins. The envelope only fills > fields the command line did not supply.

envelope: title: from-envelope
command:  --title from-flag
stored:   from-flag

The same holds for positionals, by index: a CLI positional keeps its own slot and the envelope supplies only the slots you left empty. So you can keep one envelope as a template and override a single field per invocation without editing it.

How YAML scalars are converted

YAML resolves unquoted scalars to types, and lettuce converts them back to the text the command would have received as a flag. For a string field, every one of these round-trips to its literal bytes:

| You write | Stored in a string field | Why | |---|---|---| | 007 | 007 | integer literal preserved, not renumbered | | 0x10 | 0x10 | not converted to 16 | | True | True | casing preserved (see below) | | 2026-01-02T03:04:05Z | 2026-01-02T03:04:05Z | timestamp kept as text | | << | << | merge token kept as text | | yes | yes | not a boolean in YAML 1.2 |

The reason is a single principle: the downstream validator is the one source of truth about a value. If the YAML layer silently reshaped values, the same input would mean different things through --from-yaml than through --from-json or a plain flag.

True/TRUE/False/FALSE are the case worth calling out, because YAML does resolve them to booleans. A string field keeps your literal casing; a genuine boolean field (--force, --idempotent, --bootstrap-author, --dry-run) still resolves normally, so force: True and force: true both work.

A null carries no value at all — supplying a required field as null fails exactly as if you had omitted it.

Rejected outright, so an envelope cannot mean two things: anchors, aliases, explicit tags, duplicate object keys, and non-string object keys.

Limits and refusals worth knowing

| Condition | Result | |---|---| | File larger than 64 MiB | refused before any write | | Container nesting deeper than 128 | external input nesting is too deep | | Duplicate key at any level | refused (both JSON and YAML) | | A file path escaping the store root | FW-PATH-ESCAPES-ROOT |

The size and nesting checks run before any mutation, so a rejected envelope never leaves a half-written store.

A note on where the file lives

Keep envelopes outside the store root. The store validates its own top-level paths, so a stray .yml inside --root is refused FW-PATH-UNKNOWN: unknown top-level store path — a confusing error to hit while debugging an unrelated payload.

See also

• Configuring lettuce for useful leverage — where --root, --project and --author come from, and why they stay on the command line.
• Running lettuce in autonomous agentic cycles — the loop this input path is built for.

lettuce command group Authors And Projects — 18 commands. Generated from lettuce usage --format okf (always in sync with the binary).

Back to Command Reference.

Commands in this group

• author add
• author list
• author deactivate
• author reactivate
• project create
• project set-name
• project rename
• project merge
• project list
• project show
• project archive
• project unarchive
• project move
• project delete
• project id-block grant
• project id-block list
• project author add
• project author list

---

Manage root authors, projects, and project author membership.

author add

Usage: lettuce author add AUTHOR [--idempotent]

Create a root author.

• kind: mutation
• output: object — --format plain prints its author reference (author)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: false
• stable snapshot: false
• idempotency key: true
• external input keys (these go INSIDE data, not at the top level): name
• external input envelope: {"schema_version":"v0.16","kind":"lettuce-command-input","data":{ ...command fields... }}

Flags:

• --idempotent - Treat an existing author as success.

Examples:

lettuce author add agent-1 --idempotent --format json

lettuce author add agent-1 --idempotent --format plain

Notes:

• LETTUCE_PROJECT, configuration and .lettuce project bindings are session defaults: this command still registers a store-wide author and does not link it to a project. An explicit --project is refused. Use lettuce project author add PROJECT AUTHOR for project membership.

author list

Usage: lettuce author list

List root authors. Deactivated authors (LET-693) are still listed, because they stay registered, and are also named in an inactive list.

• kind: read
• output: collection — --format plain prints one author reference (the row itself) per row of authors; nothing when empty
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: listing — proportional to the collection it reads once (paging or the task projection bound it)
• requires root: true
• requires project: false
• requires author: false
• stable snapshot: true
• idempotency key: false

Examples:

lettuce author list --format json

lettuce author list --format plain

Notes:

• LETTUCE_PROJECT, configuration and .lettuce project bindings do not filter this store-wide roster. For example, LETTUCE_PROJECT=p lettuce author list still includes authors not linked to p. An explicit --project is refused. Use lettuce project author list p to read that project's membership.

author deactivate

Usage: lettuce author deactivate AUTHOR --reason TEXT

Deactivate (revoke) a root author, append-only: the registration and all history remain, an author-deactivated event is recorded on the store-root ledger with the acting author and reason, and inactive-authors/<name> marks the author inactive. The admission gate then refuses the author as --author and as an author-valued field (FW-AUTHOR-INACTIVE).

• kind: mutation
• output: object — --format plain prints its author reference (author)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --reason text - Why the author is deactivated (required; recorded on the ledger). Required.

Examples:

lettuce author deactivate agent-1 --reason 'left the team' --author admin --format json

Notes:

• Never a delete: authors are append-only, so every record naming the author keeps resolving. The target matches case-insensitively and the stored spelling is recorded. The acting author must be registered and active; a deactivated author cannot reactivate itself. Revoking a server API token is a separate control — a token authenticates a caller, an author is an attributed name, and deactivating one never revokes the other. Over HTTP: POST /v1/authors/{author}/deactivate with a JSON reason body (admin role under --authz-policy); client mode uses it. Audit with lettuce query audit authors/<name>.

author reactivate

Usage: lettuce author reactivate AUTHOR --reason TEXT

Reverse a deactivation: records author-reactivated on the store-root ledger and removes the inactive-authors/<name> marker, so the author may act again.

• kind: mutation
• output: object — --format plain prints its author reference (author)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --reason text - Why the author is reactivated (required; recorded on the ledger). Required.

Examples:

lettuce author reactivate agent-1 --reason 'rejoined' --author admin --format json

Notes:

• Must be run by ANOTHER active author. validate reports FW-AUTHOR-STATUS-DRIFT when a marker disagrees with the ledger's latest decision (an out-of-band edit); re-running the intended verb re-aligns them.

project create

Usage: lettuce project create PROJECT [--name NAME] [--description TEXT] [--bootstrap-author] [--idempotent] [--yes] [--force]

Create a project skeleton and bootstrap registry objects. Optionally sets a human display name/description (persisted at projects/<slug>/name, /description). Creating an ADDITIONAL project into a store that already holds one requires --yes.

• kind: mutation
• output: object — --format plain prints its project reference (project)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: true
• stable snapshot: false
• idempotency key: true
• external input keys (these go INSIDE data, not at the top level): name, bootstrap_author
• external input envelope: {"schema_version":"v0.16","kind":"lettuce-command-input","data":{ ...command fields... }}

Flags:

• --name text - Optional human display name (defaults to the slug on the board title when unset).
• --description text - Optional human description of the project.
• --bootstrap-author - Create/link the acting author as project author.
• --idempotent - Treat an existing valid project as success.
• --yes - Confirm creating an ADDITIONAL project in a store that already holds one (also accepts --force).
• --force - Alias of --yes: confirm an additional project.

Examples:

lettuce project create lettuce --name Lettuce --author agent-1 --bootstrap-author --format json

lettuce project create lettuce --author agent-1 --bootstrap-author --idempotent --format plain

lettuce project create sandbox --author agent-1 --bootstrap-author --yes --format json

Notes:

• A store normally holds exactly ONE project: the board, cell coverage, run-cases and most queries are project-scoped, so a store split across several projects has no single view able to relate its tickets, cells and run-cases. Creating a SECOND project is therefore refused with FW-PROJECT-ADDITIONAL-UNCONFIRMED (naming the projects already present) unless --yes (or --force) is passed. This is a confirmation, not a ban — multi-project stores stay fully supported. The FIRST project of an empty store is never gated, and re-running create for a project that already exists (with or without --idempotent) is unaffected because it adds no project. Over HTTP the same guard applies and the acceptance is "confirm": true in the POST /v1/projects body.

project set-name

Usage: lettuce project set-name PROJECT --name NAME [--description TEXT]

Set or update an existing project's human display name (and optional description). The board title renders this name in place of the slug. Emits a project-updated lifecycle event.

• kind: mutation
• output: object — --format plain prints its project reference (project)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --name text - Human display name to set (required; empty OR whitespace-only clears back to the slug default). Required.
• --description text - Optional human description to set (empty or whitespace-only clears it).

Examples:

lettuce project set-name dashboard --name Lettuce --author agent-1 --format json

Notes:

• PROJECT (here, dashboard) must already EXIST — substitute the slug of a project you created (e.g. lettuce project create dashboard --author agent-1 --format json first, or reuse a project you already have); an unknown PROJECT is refused FW-REF-MISSING-PROJECT (check lettuce project list first). Use lettuce project create --name to name a project at creation time instead. The board title (board render) prefers this name over the project slug.

project rename

Usage: lettuce project rename OLD NEW

Rename a project's slug: move projects/OLD to projects/NEW AND rewrite every stored OLD-qualified reference (event targets, cross-object depends-on/blocks refs, object refs) so the renamed store stays strict-valid. A whole-store structural migration, applied atomically under the mutation lock. Preserves the display name and all data. Delete tombstones are write-once and are NOT rewritten (LET-1945): they move with the project, and query audit NEW/... / query timeline --task still answer an object deleted before the rename (the tombstone shows the name it was deleted under).

• kind: mutation
• output: object — --format plain prints its project reference (new_project)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: true
• stable snapshot: false
• idempotency key: false

Examples:

lettuce project rename dashboard lettuce --author agent-1 --format json

Notes:

• OLD and NEW are POSITIONAL slug arguments (not --project). Refuses if OLD does not exist (FW-PATH-NOT-FOUND), NEW already exists (a collision), or NEW is an invalid slug (FW-NAME-SLUG). REFUSES (FW-PROJECT-REF-REWRITE-UNSAFE, writing nothing) when a reference to OLD is folded into a CONTENT-ADDRESSED identity — a graph-run-case advance event or a carrier directory is named by the hash of its own payload, so rewriting such a ref would leave the object no longer addressing its own content. On any failure the store is left byte-unchanged (atomic). Verify after with lettuce validate --strict.

project merge

Usage: lettuce project merge SRC DST

Fold project SRC into project DST and remove the emptied SRC: every task, cell, artifact, comment, run, saved query, graph-def and run-case MOVES into DST, shared registry vocabulary is reconciled, and every stored SRC-qualified reference is rewritten to DST so the merged store stays valid. Rename's sibling whole-store structural migration, applied atomically under the mutation lock. Nothing is ever overwritten, auto-renamed, or silently dropped. SRC's delete tombstones move into DST's collection unrewritten (write-once, LET-1945), so query audit DST/... answers an object SRC deleted.

• kind: mutation
• output: object — --format plain prints its project reference (target_project)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: true
• stable snapshot: false
• idempotency key: false

Examples:

lettuce project merge merge-healing lettuce --author agent-1 --format json

Notes:

• SRC and DST are POSITIONAL slug arguments (not --project); BOTH must already exist. REFUSES the whole merge, writing nothing, when an object id or cell coordinate exists in BOTH projects (FW-PROJECT-MERGE-CONFLICT naming every collision) or when a registry slug both projects share differs SEMANTICALLY (the differing field is named; created/updated/revision provenance is ignored). A shared slug that matches keeps DST's copy; SRC-only objects and vocabulary move in; SRC's own display name/description are dropped with the dissolved project and echoed in dropped_source_meta. Also refuses (FW-PROJECT-REF-REWRITE-UNSAFE) when a reference to SRC is folded into a CONTENT-ADDRESSED identity (a graph-run-case advance event or a carrier directory is named by the hash of its own payload, which includes recorded effect/enrichment refs). On any failure the store is left byte-unchanged (atomic). Verify after with lettuce validate --strict.

project list

Usage: lettuce project list [--include-archived]

List project names. Archived projects are hidden unless --include-archived is passed; when they are included, the result marks which of the returned rows are archived.

• kind: read
• output: collection — --format plain prints one project reference (the row itself) per row of projects; nothing when empty
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: listing — proportional to the collection it reads once (paging or the task projection bound it)
• requires root: true
• requires project: false
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --include-archived - Include archived projects in the results (hidden by default).

Examples:

lettuce project list --format json

lettuce project list --include-archived --format plain

Notes:

• With --include-archived the JSON result carries an archived array naming which entries of projects are archived (LET-359). Before that, the inclusive listing returned archived and live projects in ONE flat list with nothing to tell them apart, so a caller who asked to SEE archived rows could not IDENTIFY them. Without the flag the key is omitted entirely and the output is byte-identical to the default listing.

project show

Usage: lettuce project show PROJECT

Show project metadata, authors, registry summary counts, and archived_at when archived. A successful read reflects THIS project's own consistency only (LET-1434 scoped gate): corruption in an unrelated part of the store is surfaced by doctor / validate --strict, not refused here.

• kind: read
• output: object — --format plain prints its project reference (project)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: bounded — bounded by the objects it names, independent of the project's size
• requires root: true
• requires project: false
• requires author: false
• stable snapshot: true
• idempotency key: false

Examples:

lettuce project show lettuce --format json

lettuce project show lettuce --format plain

Notes:

• On an ARCHIVED project this read is answered (the explicit reference is the explicit ask) and labelled ARCHIVED: an FW-READ-PROJECT-ARCHIVED-SHOWN warning (stderr in table/plain, warnings[] in json/yaml) and project_archived_at in the json/yaml data.

project archive

Usage: lettuce project archive PROJECT [--reason TEXT]

Soft-archive a project: hide it from default project list and refuse NEW work into it (FW-LIFECYCLE-PROJECT-ARCHIVED) — task create/reopen, registry/dimension/graph-def/workflow additions, leases, runs, saved queries, and (MH-12) new cells, carriers and graph-run-cases — without deleting history. Edits and wind-down of existing objects stay permitted (task set/transition, comments, re-grading an existing cell, advancing or abandoning an existing run-case). Reversible with lettuce project unarchive.

• kind: mutation
• output: object — --format plain prints its project reference (project)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --reason text - Optional reason recorded on the archive event.

Examples:

lettuce project archive lettuce --author agent-1 --reason 'Retired.' --format json

Notes:

• Archived projects are hidden from project list unless --include-archived is passed, and refuse new task create until restored. This is reversible and preserves history.

project unarchive

Usage: lettuce project unarchive PROJECT [--reason TEXT]

Restore a previously archived project back to normal visibility and re-permit new work (task create and every other accrue verb project archive refuses).

• kind: mutation
• output: object — --format plain prints its project reference (project)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --reason text - Optional reason recorded on the unarchive event.

Examples:

lettuce project unarchive lettuce --author agent-1 --format json

Notes:

• Only an archived project can be unarchived; the inverse of lettuce project archive.

project move

Usage: lettuce project move PROJECT --to-domain DEST [--from-domain SRC] [--domains-root PATH] [--yes] [--force] [--dry-run]

Move a project to ANOTHER DOMAIN of the same server (LET-1874, ADR-0028): one atomic rename of projects/PROJECT from the source domain's folder to the destination's, under BOTH domains' write locks. The destination gains every author the project names (registered with the normal author-created record) and the project-moved-in record on its root ledger; the source records project-moved-out, and a read of PROJECT there is refused FW-REF-MISSING-PROJECT naming the new domain. Nothing inside the project is rewritten: it reads byte-identically afterwards. O(1) in the project's size apart from its read-only checks. Admin-only over HTTP; needs a token that reaches BOTH domains.

• kind: mutation
• output: object — --format plain prints its project reference (project)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --to-domain domain - The destination domain (must differ from the source). Required.
• --from-domain domain - The source domain. Client mode: the request's domain for this command (default: --domain / LETTUCE_DOMAIN / the .lettuce pointer / the token's default). Operator mode: required.
• --domains-root path - Operator mode, on the server host: the server's domains root (also LETTUCE_DOMAINS_ROOT); both domains are folders under it. Refused in client mode.
• --dry-run - Report the plan — counts, the authors that would be registered in the destination, warnings and EVERY refusal — and write nothing (no lock is taken).
• --yes - Confirm the move (also accepts --force). Required unless --dry-run.
• --force - Alias of --yes.

Examples:

lettuce project move trading-bot --to-domain huru --dry-run --format json

lettuce project move trading-bot --to-domain huru --yes --format json

lettuce project move trading-bot --from-domain default --to-domain huru --domains-root /data/domains --author ops --yes

Notes:

• REFUSES, writing nothing: the destination already has PROJECT (FW-REF-EXISTS); the source lacks it (FW-REF-MISSING-PROJECT); source == destination (FW-CMD-USAGE); either domain is recovering, fenced or migrating (FW-MIGRATION-FENCED, FW-PROJECT-MOVE-DOMAIN-BUSY, runtime codes); an earlier move is unfinished (FW-PROJECT-MOVE-PENDING); the source project fails its consistency gate (FW-STORE-CONSISTENCY-GATE-FAILED); the project references, or is referenced by, ANOTHER project of either domain (FW-PROJECT-MOVE-CROSS-REFERENCE, naming every path); an author the project needs is spelled differently in the destination (FW-AUTHOR-CASE-COLLISION) or is deactivated in the source and absent from the destination (FW-AUTHOR-INACTIVE); the domains are on different filesystems (FW-PROJECT-MOVE-CROSS-DEVICE) or declare different store schemas (FW-PROJECT-MOVE-INCOMPATIBLE).
• Crash-safe: a recovery intent is written into BOTH domains before the first write; lettuce recover on either domain (or the server when it opens the domain) completes a move whose rename happened and rolls back one whose rename did not. Until then every mutation of both domains is refused FW-PROJECT-MOVE-PENDING.
• A move changes NO token grant: clients update the domain: line of their .lettuce pointer and need a token that reaches the destination. Archived projects move and stay archived. Audit: lettuce query audit PROJECT (either domain), lettuce query timeline --project PROJECT (destination).

project delete

Usage: lettuce project delete PROJECT --yes [--cascade] [--force] [--reason TEXT]

Permanently delete a project and all its history. Irreversible (unlike project archive, there is no undo). A non-empty project is refused unless --cascade is passed. Requires --yes to confirm. The delete leaves a root-surviving tombstone (actor, reason, time, every removed task) and a project-deleted event on the store-root ledger carrying the same reason, which query audit PROJECT reads back, and it carries the project's earlier task/comment/artifact tombstones with it, each with the task-deleted/comment-deleted/artifact-deleted event its delete recorded (under the same event reference), so query audit PROJECT/TASK still answers for every task the project ever deleted, with the event that deleted it.

• kind: mutation
• output: object — --format plain prints its project reference (project)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --yes - Confirm the irreversible delete (also accepts --force).
• --force - Alias of --yes: confirm the irreversible delete.
• --cascade - Also delete the project's tasks when it is non-empty.
• --reason text - Reason recorded on the project tombstone (optional; blank means none).

Examples:

lettuce project delete lettuce --author agent-1 --yes --format json

lettuce project delete lettuce --author agent-1 --yes --cascade --reason 'merged into huru' --format plain

Notes:

• Irreversible: prefer project archive when you may need the project or its history again. An empty project deletes with just --yes; a non-empty one needs --cascade.

project id-block grant

Usage: lettuce project id-block grant PROJECT AUTHOR --prefix PREFIX --start N --size N

Reserve a disjoint range of task ids to one author so task create --next cannot mint an id another clone already used. Refused if the range overlaps an existing grant.

• kind: mutation
• output: object — --format plain prints its id-block reference (first_id)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --prefix PREFIX - Id prefix the block applies to (LET, BUG). Blocks under different prefixes never conflict. Required.
• --start n - First id in the block, inclusive. Required.
• --size n - How many ids the block holds. Required.

Examples:

lettuce project id-block grant lettuce agent-2 --prefix LET --start 2000 --size 100 --author agent-1 --format json

Notes:

• The guarantee is DISJOINTNESS: an id inside a granted block cannot have been minted by another author, including in a clone this machine has never seen. That is why an overlapping grant is refused rather than merged.
• An author holding no block is unaffected and still allocates from the highest id in the local tree, with the FW-CMD-ID-ALLOCATED-FROM-LOCAL-TREE warning that says so.
• Run 'lettuce project id-block list PROJECT' first to see which ranges are already held.

project id-block list

Usage: lettuce project id-block list PROJECT

List every id block granted in a project, with each range's first and last id.

• kind: read
• output: collection — --format plain prints one id-block reference (first_id) per row of blocks; nothing when empty
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: listing — proportional to the collection it reads once (paging or the task projection bound it)
• requires root: true
• requires project: false
• requires author: false
• stable snapshot: true
• idempotency key: false

Examples:

lettuce project id-block list lettuce --format json

Notes:

• Read this before granting: a grant that overlaps an existing block is refused, and this is the only way to see which ranges are taken.
• On an ARCHIVED project this read is answered (the explicit reference is the explicit ask) and labelled ARCHIVED: an FW-READ-PROJECT-ARCHIVED-SHOWN warning (stderr in table/plain, warnings[] in json/yaml) and project_archived_at in the json/yaml data.

project author add

Usage: lettuce project author add PROJECT AUTHOR [--bootstrap-author] [--idempotent]

Link an author into a project.

• kind: mutation
• output: object — --format plain prints its author reference (author)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: true
• stable snapshot: false
• idempotency key: true
• external input keys (these go INSIDE data, not at the top level): project_name, target_author, bootstrap_author
• external input envelope: {"schema_version":"v0.16","kind":"lettuce-command-input","data":{ ...command fields... }}

Flags:

• --bootstrap-author - Create the root author if missing.
• --idempotent - Treat an existing link as success.

Examples:

lettuce project author add lettuce agent-2 --author agent-2 --idempotent --format json

lettuce project author add lettuce agent-3 --author agent-3 --bootstrap-author --idempotent --format json

lettuce project author add lettuce agent-4 --author agent-1 --idempotent --format plain

Notes:

• Link YOURSELF first: AUTHOR equal to the acting --author is a writer act on a hosted server (LET-1885), so a newcomer joins a project on its own (lettuce author add <you> --idempotent, then the first example with your name; the second example does both in one call). A MEMBER may then link another REGISTERED author (third example); a non-member linking someone else is refused FW-CMD-MISSING-AUTHOR: join first.
• --bootstrap-author for ANOTHER name registers someone else's author, which is admin on a server with an authz policy (FW-API-AUTHZ-DENIED names the role); let the teammate register itself instead. The full table is docs/guides/SERVER-SECURITY.md "Who may register authors and manage membership".

project author list

Usage: lettuce project author list PROJECT

List authors linked to a project.

• kind: read
• output: collection — --format plain prints one author reference (the row itself) per row of authors; nothing when empty
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: listing — proportional to the collection it reads once (paging or the task projection bound it)
• requires root: true
• requires project: false
• requires author: false
• stable snapshot: true
• idempotency key: false

Examples:

lettuce project author list lettuce --format json

lettuce project author list lettuce --format plain

Notes:

• On an ARCHIVED project this read is answered (the explicit reference is the explicit ask) and labelled ARCHIVED: an FW-READ-PROJECT-ARCHIVED-SHOWN warning (stderr in table/plain, warnings[] in json/yaml) and project_archived_at in the json/yaml data.

lettuce command group Cells — 28 commands. Generated from lettuce usage --format okf (always in sync with the binary).

Back to Command Reference.

Commands in this group

• cell list
• cell rollup
• cell evidence list
• cell evidence add
• cell evidence remove
• cell gate check
• cell show
• cell set
• cell clear
• cell set-where
• cell clear-where
• cell note
• cell import
• cell transition
• cell verify
• cell affirm
• board export
• board next
• board render
• cell reconcile
• dimension list
• dimension show
• dimension member list
• dimension member add
• dimension member update
• dimension declare
• dimension rename
• dimension close

---

Assert and inspect per-project coverage cells — the coordinate/state grid governed by the project's effective dimensions, states, and gates.

cell list

Usage: lettuce cell list --project PROJECT [--include-archived]

List a project's STORED cells — the explicitly-asserted coordinates and their states; the sparse pack-default space is not enumerated.

• kind: read
• output: collection — --format plain prints one cell reference (coordinate) per row of cells; nothing when empty
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: listing — proportional to the collection it reads once (paging or the task projection bound it)
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --include-archived - Read an ARCHIVED project on purpose: without this flag a read scoped to an archived project is refused (FW-READ-PROJECT-ARCHIVED); with it the read succeeds and is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning, and project_archived_at in the json/yaml data).

Examples:

lettuce cell list --project lettuce --format json

lettuce cell list --project lettuce --format plain

Notes:

• On an ARCHIVED project this read is refused with FW-READ-PROJECT-ARCHIVED (exit 1) unless --include-archived is passed; with it the result is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning and project_archived_at in the json/yaml data).

cell rollup

Usage: lettuce cell rollup --by DIMENSION --project PROJECT [--include-archived]

Roll a project's stored cells up by one dimension: the pooled floor (least-progressed) state, hardened count, non-excluded denominator, and ratio per OBSERVED member (N/A-excluded, never blended).

• kind: read
• output: report — --format plain prints the table bytes
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: listing — proportional to the collection it reads once (paging or the task projection bound it)
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --by dimension - Dimension to roll the project's stored cells up by (pooled floor, hardened count, non-excluded denominator, and ratio per observed member). Required.
• --include-archived - Read an ARCHIVED project on purpose: without this flag a read scoped to an archived project is refused (FW-READ-PROJECT-ARCHIVED); with it the read succeeds and is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning, and project_archived_at in the json/yaml data).

Examples:

lettuce cell rollup --by A --project lettuce --format json

lettuce cell rollup --by A --project lettuce --format plain

Notes:

• On an ARCHIVED project this read is refused with FW-READ-PROJECT-ARCHIVED (exit 1) unless --include-archived is passed; with it the result is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning and project_archived_at in the json/yaml data).

cell evidence list

Usage: lettuce cell evidence list COORDINATE --project PROJECT

List the evidence links on a cell. Each link's index field is its evd_<32hex> SLOT ID, NOT a numeric position — cell evidence remove accepts that slot id (or a 1-based position). The SAME evidence ledger is also projected inline by cell show --with-audit, next to the cell's derived confirmation depth and freshness — reach for that when you want the evidence in the context of the cell's audit signals rather than the links alone.

• kind: read
• output: collection — --format plain prints one evidence reference (index) per row of evidence; nothing when empty
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: bounded — bounded by the objects it names, independent of the project's size
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Examples:

lettuce cell evidence list area=auth;layer=api --project lettuce --format json

lettuce cell evidence list area=auth;layer=api --project lettuce --format plain

Notes:

• On an ARCHIVED project this read is answered (the explicit reference is the explicit ask) and labelled ARCHIVED: an FW-READ-PROJECT-ARCHIVED-SHOWN warning (stderr in table/plain, warnings[] in json/yaml) and project_archived_at in the json/yaml data.

cell evidence add

Usage: lettuce cell evidence add COORDINATE --ref REF --kind KIND --project PROJECT

Link evidence to an asserted cell (kind task=an existing task ref, validated; url=an opaque external reference); records a cell-evidence event.

• kind: mutation
• output: object — --format plain prints its evidence reference (index)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --ref ref - Evidence reference: an existing task ref (with --kind task, validated to exist) or an opaque external reference (with --kind url). Required.
• --kind kind - Evidence kind: task (ref validated to exist) or url (any non-empty opaque string). Required.

Examples:

lettuce cell evidence add area=auth;layer=api --ref lettuce/LET-1 --kind task --project lettuce --author agent-1 --format json

Notes:

• The cell must already be asserted (cell set/transition). A task ref is validated to exist; url is any non-empty string.

cell evidence remove

Usage: lettuce cell evidence remove COORDINATE --index N --project PROJECT

Remove one evidence link from an asserted cell; records a cell-evidence-remove event. The inverse of cell evidence add — drop stale evidence so a guard-bite gate must be re-proven on fresh evidence. --index names the link EITHER as its evd_<32hex> slot id (the index field from cell evidence list) OR as its 1-based positive position (1 = the first link); --index 0 is refused.

• kind: mutation
• output: object — --format plain prints its evidence reference (index)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --index n - The evidence link to remove: its evd_<32hex> slot id (shown as index by cell evidence list), or its 1-based positive position (1 = the first link). --index 0 is refused; an absent target is refused FW-PATH-NOT-FOUND. Required.

Examples:

lettuce cell evidence remove area=auth;layer=api --index 2 --project lettuce --author agent-1 --format json

Notes:

• The cell must be asserted and carry an evidence entry at the named link. Surviving links keep their slot ids (no renumber).

cell gate check

Usage: lettuce cell gate check COORDINATE --gate SLUG --project PROJECT

Evaluate one gate declared by the active pack against a cell, returning {gate, coordinate, passed, reason}. Built-in evaluators: consistency (a STORE-WIDE predicate: the whole store root validates clean. It IGNORES the COORDINATE, so every cell in the store gets the same verdict, and it is not project-scoped either — a fault in another project sharing the root fails this check) and guard-bite (the cell carries >=1 AUTHORISING evidence link — a task link that still RESOLVES to a DONE task carrying custom/grc, so a link citing a DELETED task is a phantom and fails; a url link is stored and counted as evidence but ANNOTATES ONLY and cannot open a gated state, so a cell whose only evidence is a url still fails). Read-only; an unknown gate is refused FW-GATE-UNKNOWN. The exit code encodes the verdict (LET-1819, the LET-415 query shape): a well-formed check always returns ok:true with the verdict in data, and exits 0 on PASS or 2 on FAIL. Exit 1 is a usage error or refusal.

• kind: read
• output: verdict — --format plain prints the cell reference (coordinate) iff passed is true; nothing otherwise (the explanation on stderr; the exit code is the answer)
• exit codes: 0 yes (passed); 2 no: the answer, not a failure (ok:true; output contract R6); any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: store-inline — walks the whole store inside the request (not yet a server-owned job; it can outlast the client timeout on a large hosted store)
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --gate slug - Gate slug to evaluate (built-in evaluators: consistency, guard-bite); an unknown gate is refused FW-GATE-UNKNOWN. Required.

Examples:

lettuce cell gate check area=auth;layer=api --gate guard-bite --project lettuce --format json

lettuce cell gate check area=auth;layer=api --gate consistency --project lettuce --format plain

Notes:

• On an ARCHIVED project this read is answered (the explicit reference is the explicit ask) and labelled ARCHIVED: an FW-READ-PROJECT-ARCHIVED-SHOWN warning (stderr in table/plain, warnings[] in json/yaml) and project_archived_at in the json/yaml data.

cell show

Usage: lettuce cell show COORDINATE [--with-references] [--with-audit] --project PROJECT

Show the asserted state of a cell at a coordinate; an untouched coordinate reports the active pack's sparse DEFAULT state (stored=false) computed, not stored. --with-references adds a referenced_by projection — the graph-run-cases whose effects reference this cell (INT-15b provenance surfaced inline; the reverse of graph-run-case refs-to). --with-audit adds the LET-418 evidentiary projection — the cell's EVIDENCE links (the same ledger cell evidence list reads) surfaced under audit.evidence, alongside the derived confirmation depth/freshness and the confirmation ledger. So a cell's evidence IS reachable from cell show --with-audit; you do not have to go to cell evidence list to see it.

• kind: read
• output: object — --format plain prints its cell reference (coordinate)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: bounded — bounded by the objects it names, independent of the project's size
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --with-references - Include the referenced_by back-reference projection: the graph-run-cases whose recorded produced-effects reference THIS cell (which run-case decisions hardened/touched it). Opt-in (default off keeps the cheap bare read). Surfaced in the machine formats (json/yaml) and the human table — always present there when set, an empty [] when nothing references the cell. An inclusion flag: refused under --format plain (FW-CMD-USAGE, output contract D1), which prints the bare coordinate; read the projection with table/json/yaml.
• --with-audit - Include the LET-418 evidentiary projection under audit: the cell's EVIDENCE links (audit.evidence — the SAME ledger cell evidence list reads, via ops.ListCellEvidence), plus the derived depth/depth_verify/depth_affirm, freshness/freshness_basis, and the confirmation LEDGER those figures are derived from. This is where a cell's evidence surfaces on cell show. Before this flag cell show returned state/stored/note only and the confirmation ledger had NO read surface at all, so the signals that reveal DoD gaming — is this hardened cell evidence-backed, how deep, how stale, who attested it — were readable only via board export and FQL. Composed from the SAME readers the board and the DoD verdict use, so the audit can never disagree with the gate. OPT-IN because it needs a whole-project provenance fold (the freshness reference revisions), cached by writer-generation; a bare cell show stays a cheap point read. Local store only: refused in client mode rather than silently answering without the projection.

Examples:

lettuce cell show area=auth;layer=api --project lettuce --format json

lettuce cell show area=auth;layer=api --with-references --project lettuce --format json

lettuce cell show area=auth;layer=api --with-audit --project lettuce --format json

lettuce cell show area=auth;layer=api --project lettuce --format plain

Notes:

• To see a cell's EVIDENCE links, run cell show --with-audit — it projects the evidence ledger (audit.evidence) alongside the derived confirmation depth, freshness, and confirmation ledger — or cell evidence list COORDINATE for the evidence links alone. A bare cell show (no flag) omits evidence by design, so the absence of an evidence field there does NOT mean the cell has none.
• On an ARCHIVED project this read is answered (the explicit reference is the explicit ask) and labelled ARCHIVED: an FW-READ-PROJECT-ARCHIVED-SHOWN warning (stderr in table/plain, warnings[] in json/yaml) and project_archived_at in the json/yaml data.

cell set

Usage: lettuce cell set COORDINATE --state STATE [--facilitate] [--note TEXT] [--reason REASON] --project PROJECT

Assert a cell's state at a coordinate (canonicalized dim=member;dim=member), recording a cell-set event; the state must be in the project's active pack vocabulary. --note persists a first-class rationale scalar on the cell (queryable via cell show, projected as cells[].reason in board export).

• kind: mutation
• output: object — --format plain prints its cell reference (coordinate)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --state state - State to assert at the coordinate; must be in the active pack's state vocabulary. Required.
• --reason reason - Optional justification for the assertion, recorded on the cell-set EVENT (most meaningful when asserting a waived/excluded state — captures WHY the cell is out of scope).
• --note text - Optional FIRST-CLASS rationale (GAP-2) persisted as a scalar ON the cell — read back by cell show and projected as cells[].reason in board export. Distinct from --reason (event-only). Omitting --note preserves any existing note; clear a note with cell note COORD "".
• --facilitate - Record-not-enforce a direct set into a GATE-ENTRY-ONLY state: assert it even though no gate guarding entry passed, recording the failed gate verdict on the cell-set event (the same annotation cell transition --facilitate writes).

Examples:

lettuce cell set area=auth;layer=api --state in_progress --project lettuce --author agent-1 --format json

lettuce cell set area=auth;layer=api --state waived --reason 'platform not in scope for v1' --project lettuce --author agent-1 --format json

lettuce cell set area=auth;layer=api --state hardened --note 'covered by TestAuthApiHardened (bite-verified)' --project lettuce --author agent-1 --format json

lettuce cell set area=auth;layer=api --state hardened --facilitate --reason 'onboarding a hand-graded corpus' --project lettuce --author agent-1 --format json

Notes:

• The coordinate is canonicalized (dimensions sorted, deduplicated) and the state validated against the active pack's states; a malformed coordinate or unknown state is refused. An optional --reason justification is durably recorded on the cell-set event (the same rationale mechanism cell transition uses); an optional --note persists a first-class rationale scalar on the cell itself (GAP-2), read back by cell show and projected as cells[].reason in board export. The reserved scope= member partitions the DoD/board: a coordinate with a scope= lands in that scope, one WITHOUT a scope= is bucketed under the synthetic scope unscoped at evaluation time (so it always counts — never vacuously done); asserting an explicit scope=unscoped is refused (FW-NAME-RESERVED) since that name is reserved for the bucket. PROMOTION INTEGRITY: a state the active pack lets you enter ONLY through gated transitions (e.g. hardened, entered only by harden behind the guard-bite gate) is GATE-ENTRY-ONLY — a direct set into it must satisfy at least one of those gates or it is refused FW-WF-GATE-UNSATISFIED; --facilitate applies it anyway and records the failed verdict on the event. A state with ANY ungated way in (or none at all, like the pack default) is unaffected. UNREASONED EXCLUSIONS (LET-417): a state whose every declared entry requires: [reason] (waived, excluded, gap, blocked on the bundled pack) is NEVER refused, but a direct set into it with neither --reason nor --note is recorded UNREASONED (the result's unreasoned: true, a cell unreasoned marker, an [unreasoned] event segment). An unreasoned waived/excluded cell does NOT leave the hardened_ratio/DoD denominator — it stays applicable (and fails the DoD grade floor) and is counted as unreasoned_exclusions on the board headline, the rollup rows and the DoD verdict. Re-set it with --reason/--note (or reach it via cell transition) to make it a real N/A.

cell clear

Usage: lettuce cell clear COORDINATE --project PROJECT

Remove a stored cell so its coordinate reverts to the active pack's sparse default (stored=false); a coordinate that was never asserted is refused.

• kind: mutation
• output: object — --format plain prints its cell reference (coordinate)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Examples:

lettuce cell clear area=auth;layer=api --project lettuce --author agent-1 --format json

Notes:

• Hard-removes the cell's stored assertion; clearing an un-asserted coordinate is refused.

cell set-where

Usage: lettuce cell set-where --where '<fql>' --state GRADE [--reason TEXT] [--confirm] [--dry-run] [--facilitate] --project PROJECT

Bulk-assert one state (grade) on EVERY stored cell matching an FQL predicate over the cells source (the same engine query run / cell list back — reuse the scope/unit/dim/group/kind/grade columns to slice a dimension). Requires --confirm to mutate more than one cell; --dry-run lists the matched cells without writing, and predicts what the apply will do with them: for a gate-entry-only target it names the gates (gate_entry_only, gates) and lists the matched cells the apply will SKIP on a failed entry gate under skipped/skipped_count, with the apply's own reason (LET-1576; not under --facilitate, which records the bypass instead). The whole batch is applied under ONE store mutation lock (byte-identical to N individual cell set calls), so no concurrent writer interleaves.

• kind: mutation
• output: collection — --format plain prints one cell reference (coordinate) per row of set or coordinates; nothing when empty; its report findings announced on stderr
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --where fql - FQL predicate over the cells source selecting the cells to mutate (same syntax as query run 'from cells where ...'). Required.
• --state grade - Grade to assert on every matched cell; must be in the active pack's state vocabulary. Required.
• --reason text - Optional justification recorded on each cell-set event (most meaningful when asserting a waived/excluded grade).
• --facilitate - Record-not-enforce a bulk assert into a GATE-ENTRY-ONLY grade: apply it to matched cells whose entry gates fail, recording the failed verdict on each cell-set event. Without it those cells are skipped and reported.
• --confirm - Confirm applying the change to all matched cells (required for more than one match).
• --dry-run - List the matched cells and intended change without writing.

Examples:

lettuce cell set-where --where 'scope = s1 and grade = evidence_linked' --state hardened --confirm --project lettuce --author agent-1 --format json

lettuce cell set-where --where 'unit = cell-set' --state hardened --dry-run --project lettuce --author agent-1 --format json

Notes:

• Bulk operation over an FQL-selected set; local filesystem or dedicated-git mode only. In HTTP client mode, mutate individual coordinates with cell set.

cell clear-where

Usage: lettuce cell clear-where --where '<fql>' [--confirm] [--dry-run] --project PROJECT

Bulk-remove EVERY stored cell matching an FQL predicate so each coordinate reverts to the active pack's sparse default (the bulk inverse of cell clear). Requires --confirm to clear more than one cell; --dry-run lists the matched cells without writing. Applied under ONE store mutation lock.

• kind: mutation
• output: collection — --format plain prints one cell reference (coordinate) per row of cleared or coordinates; nothing when empty; its report findings announced on stderr
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --where fql - FQL predicate over the cells source selecting the cells to clear (same syntax as query run 'from cells where ...'). Required.
• --confirm - Confirm clearing all matched cells (required for more than one match).
• --dry-run - List the matched cells without writing.

Examples:

lettuce cell clear-where --where 'grade = untested' --confirm --project lettuce --author agent-1 --format json

Notes:

• Bulk operation over an FQL-selected set; local filesystem or dedicated-git mode only. In HTTP client mode, clear individual coordinates with cell clear.

cell note

Usage: lettuce cell note COORDINATE [TEXT] --project PROJECT

Set (or, with no/empty TEXT, CLEAR) a cell's first-class NOTE — the operator rationale scalar (GAP-2), orthogonal to the cell's state, so you can annotate WHY a cell holds its grade without re-asserting the grade. Read back by cell show and projected as cells[].reason in board export. The cell must already be asserted (a note needs a cell).

• kind: mutation
• output: object — --format plain prints its cell reference (coordinate)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Examples:

lettuce cell note area=auth;layer=api 'grade held by TestAuthApiHardened; last audited 2026-07' --project lettuce --author agent-1 --format json

lettuce cell note area=auth;layer=api --project lettuce --author agent-1 --format json

Notes:

• Records a cell-note event and persists (or removes) the cell's note scalar under one lock with a read-back verify. Annotating an un-asserted coordinate is refused (assert it with cell set first). Omitting TEXT (or passing "") clears the note. Same rationale reachable at assert time via cell set --note, and over HTTP through the cell set PUT body; the dedicated cell note command is local and dedicated-git modes only.

cell import

Usage: lettuce cell import --file PATH [--confirm] [--dry-run] [--facilitate] --project PROJECT

Bulk-ASSERT many cells to their OWN explicit states from a FILE in one locked batch (GAP-8) — the bulk assert cell verify --coords-file (bulk confirm) and cell set-where (bulk set by predicate) left. Each file line is coordinate<TAB>state[<TAB>note]; blank lines and #-comments are ignored. Requires --confirm to assert more than one cell; --dry-run previews the parsed assertions without writing, listing under skipped every line the apply will skip — malformed, off a closed dimension, an unknown state, or (LET-1576) a gate-entry-only state whose entry gate fails, with the apply's own reason. The whole batch applies under ONE store mutation lock (byte-identical to N cell set calls).

• kind: mutation
• output: collection — --format plain prints one cell reference (coordinate) per row of set or assertions; nothing when empty; its report findings announced on stderr
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --file path - Path to the import file: one assertion per line, coordinate<TAB>state[<TAB>note]. Blank lines and #-comments ignored; a malformed line (missing TAB-separated state, empty coordinate/state), an invalid coordinate, or an unknown state is skipped and reported, never aborting the batch. Required.
• --facilitate - Record-not-enforce rows asserting a GATE-ENTRY-ONLY state: apply them even though no entry gate passed, recording the failed verdict on each cell-set event. Without it those rows are skipped and reported — this is the flag for onboarding an externally-graded corpus.
• --confirm - Confirm applying every parsed assertion (required for more than one assertion).
• --dry-run - List the parsed assertions and skipped lines without writing.

Examples:

lettuce cell import --file ./cells.tsv --confirm --project lettuce --author agent-1 --format json

lettuce cell import --file ./cells.tsv --dry-run --project lettuce --author agent-1 --format json

Notes:

• Bulk file operation; local filesystem or dedicated-git mode only. Input is supplied with --file PATH (coordinate<TAB>state[<TAB>note]); this command has no --coords-file form.

cell transition

Usage: lettuce cell transition COORDINATE ACTION [--reason TEXT] [--facilitate] --project PROJECT

Move a cell to a new state through the active pack's workflow (an action with no legal transition from the cell's current state is refused); records a cell-transition event carrying the fired action and the from/to states it resolved (MH-9), so readers need not replay the pack. A transition that declares a gate must PASS it (FW-WF-GATE-UNSATISFIED otherwise); --facilitate records the gate verdict on the event but allows the move (record-not-enforce). A transition whose pack entry declares requires: [reason] is refused (FW-CMD-MISSING-ARGUMENT) without --reason.

• kind: mutation
• output: object — --format plain prints its cell reference (coordinate)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --reason text - Why this move was made — REQUIRED by any transition whose pack entry declares requires: [reason]. In the shipped coverage pack that is flag-gap, block, waive and exclude: each records a judgement someone must later be able to question (this is a gap / this is blocked / this is out of scope), so the reason is the durable half of the assertion. Recorded on the cell-transition event. Run lettuce defaults show and read the REQUIRES column for the transitions in force on YOUR project.
• --facilitate - Record the gate verdict on the event but allow a gated transition to proceed even if its gate fails (record-not-enforce).

Examples:

lettuce cell transition area=auth;layer=api plan --project lettuce --author agent-1 --format json

lettuce cell transition area=auth;layer=api flag-gap --reason 'the cited spec is not in this repo' --project lettuce --author agent-1 --format json

lettuce cell transition area=auth;layer=api harden --facilitate --project lettuce --author agent-1 --format json

Notes:

• The action must name a transition legal from the cell's current state in the active pack (see lettuce defaults show); an untouched coordinate starts at the pack default. A gated transition (e.g. harden requires the guard-bite gate) is refused unless the gate passes or --facilitate is given.
• lettuce defaults show is the authority on which actions your project requires a --reason for: its REQUIRES column is resolved from the base convention PLUS the project's own tweak layer, so a project that declares an extra reason-requiring transition is reflected there and cannot be read off this page.

cell verify

Usage: lettuce cell verify COORDINATE [--evidence REF] [--reason TEXT] --project PROJECT | lettuce cell verify --coords-file PATH [--evidence REF] [--reason TEXT] --project PROJECT

Append a VERIFY confirmation to a cell's FRESH-2 confirmation ledger — an INDEPENDENT re-check that the cell's current grade still holds (the stronger durability signal), recorded with the store revision at confirmation time so the cell's distinct-rev hardening DEPTH deepens. Never changes the grade or the hardened ratio; depth is derived (never a settable counter). The STRONG depth (depth_verify — the one the DoD depth floor keys off) counts a verify ONLY when it carries --evidence (a per-cell re-exercise reference); an evidence-less verify records but is demoted to affirm-tier depth, so a bulk stamp with no per-cell proof earns NO verify-depth (the un-fakeable anti-rubber-stamp rule). A given --evidence ref earns verify-depth ONCE PER CELL: the first verify citing it deepens depth_verify, and a later verify on the SAME cell citing the SAME ref is demoted to affirm-tier EVEN AT A NEW STORE REVISION, because one unit of proof is not N independent re-exercises (LET-414-B distinct-EVIDENCE, which is stricter than the distinct-rev rule below). The de-duplication is per-cell, so one ref shared across DIFFERENT cells — the --coords-file pattern — still deepens each of them. Confirming twice at the same store revision buys no depth (the distinct-rev anti-farming rule); a grade change resets depth to the new grade's confirmations only. --coords-file confirms MANY cells in one call (bulk), computing the store subject revision ONCE for the whole batch — the O(n^2)->O(n) fix for a large hardening pass, byte-identical to N individual verifies.

• kind: mutation
• output: collection — --format plain prints one cell reference (coordinate) per row of confirmed, or the one cell it acted on
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --evidence ref - Per-cell re-exercise reference (guard-test name, run id, or URL) proving this verify independently re-checked the cell. REQUIRED for the verify to strengthen depth_verify (the DoD depth floor keys off it); an evidence-less verify still records but only as affirm-tier depth. Re-using the SAME ref on the SAME cell deepens depth_verify only the FIRST time — later repeats record as affirm-tier even at a new revision. With --coords-file the one ref is applied to EVERY coordinate in the batch.
• --reason text - Optional justification recorded on the cell-confirm event (auditable; a rubber-stamp confirmation stays attributable).
• --coords-file path - Bulk mode: confirm every newline-separated coordinate in this file in ONE call (blank lines and #-comments ignored). Computes the subject revision ONCE for the whole batch (O(n^2)->O(n)); each cell's confirmation is byte-identical to an individual cell verify. Mutually exclusive with the COORDINATE positional; a coordinate with no asserted cell (or a malformed line) is skipped and reported, never aborting the batch.

Examples:

lettuce cell verify area=auth;layer=api --evidence 'go test ./... -run TestAuthAPI' --project lettuce --author agent-1 --format json

lettuce cell verify --coords-file ./coords.txt --evidence CI#1234 --project lettuce --author agent-1 --format json

Notes:

• The cell must already be asserted (cell set/transition). Depth = count of DISTINCT confirmation revisions of the current grade (verify + affirm reported separately, never blended); an unconfirmed cell reads depth 0. depth_verify counts ONLY evidence-backed verifies (--evidence) whose ref is DISTINCT for that cell — the DoD depth floor is satisfied by proven re-exercise, never a bare stamp and never one proof cited N times. Both mutations still return ok:true when a repeat is demoted, so read depth_verify back (query from cells select depth_verify, or board export) rather than inferring it from the call succeeding. --coords-file bulk-confirms a coordinate list (skipping unasserted/malformed lines) with one shared --evidence; the batch is semantically identical to N individual verifies but O(n) not O(n^2). A single coordinate is available through the local or hosted backend; --coords-file remains store-local.

cell affirm

Usage: lettuce cell affirm COORDINATE [--reason TEXT] --project PROJECT | lettuce cell affirm --coords-file PATH [--reason TEXT] --project PROJECT

Append an AFFIRM confirmation to a cell's FRESH-2 confirmation ledger — a RESTATEMENT that the cell's current grade still holds (an agentic re-examination, the weaker signal vs verify), recorded with the store revision at confirmation time so the cell's distinct-rev hardening DEPTH deepens. Never changes the grade or the hardened ratio; depth is derived (never a settable counter). Confirming twice at the same store revision buys no depth (the distinct-rev anti-farming rule); a grade change resets depth to the new grade's confirmations only. --coords-file confirms MANY cells in one call (bulk), computing the store subject revision ONCE for the whole batch — the O(n^2)->O(n) fix for a large hardening pass, byte-identical to N individual affirms.

• kind: mutation
• output: collection — --format plain prints one cell reference (coordinate) per row of confirmed, or the one cell it acted on
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --reason text - Optional justification recorded on the cell-confirm event (auditable; a rubber-stamp confirmation stays attributable).
• --coords-file path - Bulk mode: confirm every newline-separated coordinate in this file in ONE call (blank lines and #-comments ignored). Computes the subject revision ONCE for the whole batch (O(n^2)->O(n)); each cell's confirmation is byte-identical to an individual cell affirm. Mutually exclusive with the COORDINATE positional; a coordinate with no asserted cell (or a malformed line) is skipped and reported, never aborting the batch.

Examples:

lettuce cell affirm area=auth;layer=api --reason 're-reviewed against head' --project lettuce --author agent-1 --format json

lettuce cell affirm --coords-file ./coords.txt --project lettuce --author agent-1 --format json

Notes:

• The cell must already be asserted (cell set/transition). Depth = count of DISTINCT confirmation revisions of the current grade (verify + affirm reported separately, never blended); an unconfirmed cell reads depth 0. --coords-file bulk-confirms a coordinate list (skipping unasserted/malformed lines); the batch is semantically identical to N individual affirms but O(n) not O(n^2). A single coordinate is available through the local or hosted backend; --coords-file remains store-local.

board export

Usage: lettuce board export --project PROJECT [--source-rev REV] [--wait[=DURATION] | --no-wait] [--include-archived]

Project a project's coverage board into a stable, versioned BoardExport v0.1 JSON DATA CONTRACT (schema_version, generated_at, source_rev, pack dimensions + state legend, stored cells with evidence, per-axis coverage rollups, blended headline ratio, milestones, and tickets) for a dashboard renderer. Read-only projection: emits the document as the machine envelope data on stdout (pipe it or read .data), never writes a file or mutates the store; visuals live outside the contract (data separate from visual). Distinct from export (a whole-store backup bundle).

• kind: read
• output: report — --format plain prints the table bytes
• exit codes: 0 success; 8 hosted result not ready yet (FW-API-HEALTH-PENDING / FW-API-READ-PENDING): retry later or --wait; not a finding; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: project — walks the whole project: on a hosted server a background build (--wait[=DURATION] / --no-wait; exit 8 while it is pending)
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --source-rev rev - Optional provenance revision (repo commit short-SHA or store revision) stamped into source_rev. generated_at is NOT a wall-clock stamp: with none supplied it defaults from the STORE — the instant of the latest event — so repeated exports of an unchanged store are byte-identical and it advances only when the store does. The whole projection, provenance included, is reproducible.
• --wait - Hosted stores only (LET-1846): written --wait or --wait=DURATION. How long to wait for a PENDING server-side build (FW-API-READ-PENDING), polling with the server's Retry-After; progress on stderr. The default already waits 3m; an explicit --wait also polls while the answer is STALE and its rebuild is running, until a current one is built or the budget ends. A spent budget exits 8. No effect locally.
• --no-wait - Hosted stores only (LET-1846): do not wait for a pending server-side build; exit 8 (FW-API-READ-PENDING, try again later) at once. A current or stale result is still printed. No effect locally.
• --include-archived - Read an ARCHIVED project on purpose: without this flag a read scoped to an archived project is refused (FW-READ-PROJECT-ARCHIVED); with it the read succeeds and is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning, and project_archived_at in the json/yaml data).

Examples:

lettuce board export --project lettuce --format json

lettuce board export --project lettuce --source-rev a1b2c3d --format json

Notes:

• BoardExport is a lossy presentation-oriented projection of the coverage board only (cells + rollups + milestones + tickets), NOT the store-bundle export (lettuce export --bundle), which is a faithful full backup. The two do not share a schema. See docs/specs/board-export-v0.1.md.
• Per-axis rollups are keyed by the real coordinate axis name (e.g. by_axis.dim, by_axis.command); the blended headline is Sigma-hardened / Sigma-non-excluded over every stored cell. cells[].reason is reserved but empty in this release (GAP-2: cells carry no first-class reason field). REST parity is deferred (CLI-first).
• Hosted (LET-1846): the server builds the board in the BACKGROUND (single-flight per domain, project and options, detached from the request, cached per writer generation, rebuilt after writes) and never inline, so a proxy timeout cannot cancel it. You get the board current at this generation, the LAST built board marked STALE while it rebuilds (a slightly old board still says what to work on), or 503 FW-API-READ-PENDING when none was built yet. The client waits for a pending build by default (polling with Retry-After, progress on stderr, up to --wait=DURATION, default 3m); --no-wait, or a spent budget, exits 8 (try again later, never 1). Provenance: one board: line on stderr in human formats (fresh | current | STALE + age); meta.read_kind, read_source, generation, computed_at, age_seconds, stale, current_generation, read_refresh in machine formats. An explicit --wait also waits out a stale board's rebuild.
• On an ARCHIVED project this read is refused with FW-READ-PROJECT-ARCHIVED (exit 1) unless --include-archived is passed; with it the result is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning and project_archived_at in the json/yaml data).

board next

Usage: lettuce board next --project PROJECT [--depth 0|1|2] [--scope SLUG] [--wait[=DURATION] | --no-wait] [--include-archived]

Agent-facing coverage ORIENTATION report — "what should I harden next?" — distilled from the same board board export produces, so an agent picks its next target WITHOUT exporting and re-parsing the whole board. Read-only: every scope's meter ranked WEAKEST-FIRST plus a single "start here" pointer (the globally weakest open cell). --depth deepens the detail (the operator's global-to-increasing-detail): 0 (default) meters + start-here; 1 adds every scope's shape-aware suggestions (a heatmap scope → its dimensions with H/G/U subcounts, a scalars scope → its scalar grades, a ladder scope → its milestones) weakest-first; 2 adds the weakest units + the concrete open (gap/untested) cell coordinates, capped with an honest +N-more pointer. --scope restricts the report to one scope. The default output is a SELF-GUIDING plain-text report: every summarised node prints the exact lettuce ... command to descend, so the agent is never stuck; --format json emits the same data structured (scopes[] each with meter + suggestions[] + coordinates[] + a more drill string), depth-trimmed to match.

• kind: read
• output: report — --format plain prints the table bytes
• exit codes: 0 success; 8 hosted result not ready yet (FW-API-HEALTH-PENDING / FW-API-READ-PENDING): retry later or --wait; not a finding; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: project — walks the whole project: on a hosted server a background build (--wait[=DURATION] / --no-wait; exit 8 while it is pending)
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --depth 0|1|2 - How much detail to surface: 0 (default) per-scope meters + start-here; 1 adds every scope's dimension/milestone subcounts weakest-first; 2 adds the weakest units + concrete open coordinates. Never hides a whole scope — only how deep each goes.
• --scope slug - Restrict the report to one scope member (e.g. s1); a slug that names no scope on the board is refused with the available list.
• --wait - Hosted stores only (LET-1846): written --wait or --wait=DURATION. How long to wait for a PENDING server-side build (FW-API-READ-PENDING), polling with the server's Retry-After; progress on stderr. The default already waits 3m; an explicit --wait also polls while the answer is STALE and its rebuild is running, until a current one is built or the budget ends. A spent budget exits 8. No effect locally.
• --no-wait - Hosted stores only (LET-1846): do not wait for a pending server-side build; exit 8 (FW-API-READ-PENDING, try again later) at once. A current or stale result is still printed. No effect locally.
• --include-archived - Read an ARCHIVED project on purpose: without this flag a read scoped to an archived project is refused (FW-READ-PROJECT-ARCHIVED); with it the read succeeds and is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning, and project_archived_at in the json/yaml data).

Examples:

lettuce board next --project lettuce --format json

lettuce board next --project lettuce --depth 2 --format json

Notes:

• A pure READ over the same BoardExport as board export/board render: it never mutates the store and honours the identical project-scoping contract — a PROJECT CONTEXT is REQUIRED — resolved from --project, else LETTUCE_PROJECT, else config project: — and a MISSING context is refused FW-CMD-MISSING-PROJECT-CONTEXT while an INVALID name is refused FW-NAME-PROJECT (LET-264 split them; an EMPTY value counts as missing, not malformed). The diagnostic names CONTEXT, not the flag, for exactly this reason and it reads ONLY the named project's board, never a default or a cross-project scan. Frontier = the not-done, not-excluded, not-smoke cells (gap + untested), derived from the pack's state vocabulary, never a hardcoded slug. Same honesty invariants as the board: never invents a cell, never blends across scopes, an empty denominator reads n/a (in JSON a PRESENT hardened_ratio: null / suggestion ratio: null with its testable: 0 — the same encoding board export and cell rollup publish, never an omitted key; LET-1509), and a capped list always announces its full count + the drill command (no silent truncation). An empty frontier is only complete when cells exist: the JSON always carries total_cells, and a project with ZERO stored cells reads UNSCOPED ('no cells defined yet'), never 'every cell is hardened or excluded' — with or without a declared DoD (LET-465). Under a DoD the '✓ DoD met' line prints only when the verdict IS met: a project with no DoD-applicable cell (zero cells, or every cell excluded) lists '[✕] coverage — no DoD-applicable cell' as its blocker instead. With a declared grid, an off-grid cell (unit or dim not declared) never counts toward its scope (LET-531). REST parity is deferred (CLI-first), mirroring board export/render.
• Hosted (LET-1846): the server builds the board in the BACKGROUND (single-flight per domain, project and options, detached from the request, cached per writer generation, rebuilt after writes) and never inline, so a proxy timeout cannot cancel it. You get the board current at this generation, the LAST built board marked STALE while it rebuilds (a slightly old board still says what to work on), or 503 FW-API-READ-PENDING when none was built yet. The client waits for a pending build by default (polling with Retry-After, progress on stderr, up to --wait=DURATION, default 3m); --no-wait, or a spent budget, exits 8 (try again later, never 1). Provenance: one board: line on stderr in human formats (fresh | current | STALE + age); meta.read_kind, read_source, generation, computed_at, age_seconds, stale, current_generation, read_refresh in machine formats. An explicit --wait also waits out a stale board's rebuild.
• On an ARCHIVED project this read is refused with FW-READ-PROJECT-ARCHIVED (exit 1) unless --include-archived is passed; with it the result is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning and project_archived_at in the json/yaml data).

board render

Usage: lettuce board render --project PROJECT [--theme SLUG] [--source-rev REV] [--wait[=DURATION] | --no-wait] [--include-archived]

Render a project's coverage board as a SELF-CONTAINED HTML page (zero-JS, except the one inline grc replay script a project with graph-run-cases carries) NATIVELY in Go from the same BoardExport board export produces — no external python, no JSON round-trip. Read-only projection: the raw HTML is written to stdout so a publisher pipes it to a file; a machine --format (json/yaml) wraps it in the envelope's data as a {theme, format, content} object. DATA ⟂ PRESENTATION: the data/structure is theme-independent and a --theme selects only the presentation (an unknown theme is refused with the available list). Reproducible: with no --source-rev the provenance defaults from the store (data revision + latest-event instant), never the wall clock. REST parity is deferred (CLI-first), mirroring board export/next.

• kind: read
• output: content — --format plain prints the content, as table prints it
• exit codes: 0 success; 8 hosted result not ready yet (FW-API-HEALTH-PENDING / FW-API-READ-PENDING): retry later or --wait; not a finding; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: project — walks the whole project: on a hosted server a background build (--wait[=DURATION] / --no-wait; exit 8 while it is pending)
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --theme slug - Presentation theme selecting only the CSS/frame (data is theme-independent); defaults to the built-in default theme. An unknown theme is refused with the available list.
• --source-rev rev - Optional provenance revision (repo commit short-SHA or store revision) stamped into the masthead; with none it defaults from the store (data revision + latest-event instant) for a wall-clock-free, reproducible render.
• --wait - Hosted stores only (LET-1846): written --wait or --wait=DURATION. How long to wait for a PENDING server-side build (FW-API-READ-PENDING), polling with the server's Retry-After; progress on stderr. The default already waits 3m; an explicit --wait also polls while the answer is STALE and its rebuild is running, until a current one is built or the budget ends. A spent budget exits 8. No effect locally.
• --no-wait - Hosted stores only (LET-1846): do not wait for a pending server-side build; exit 8 (FW-API-READ-PENDING, try again later) at once. A current or stale result is still printed. No effect locally.
• --include-archived - Read an ARCHIVED project on purpose: without this flag a read scoped to an archived project is refused (FW-READ-PROJECT-ARCHIVED); with it the read succeeds and is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning, and project_archived_at in the json/yaml data).

Examples:

lettuce board render --project lettuce

lettuce board render --project lettuce --theme default

lettuce board render --project lettuce --format json

Notes:

• A pure READ over the same BoardExport as board export/board next: it never mutates the store and honours the identical project-scoping contract — a PROJECT CONTEXT is REQUIRED — resolved from --project, else LETTUCE_PROJECT, else config project: — and a MISSING context is refused FW-CMD-MISSING-PROJECT-CONTEXT while an INVALID name is refused FW-NAME-PROJECT (LET-264 split them; an EMPTY value counts as missing, not malformed). The diagnostic names CONTEXT, not the flag, for exactly this reason and it reads ONLY the named project's board. The HTML is strictly self-contained: every byte is inline — no src=, no external http(s) reference the browser resolves (the only http(s) strings are the SVG xmlns and inert provenance URLs inside title= tooltips), and no network call of any kind (no cdn/fetch/XHR/WebSocket/dynamic import). It is pure-CSS with ONE authorized exception (operator 20974/21127): a project carrying graph-run-cases also emits the grc replay simulator as exactly one INLINE <script> (an IIFE) plus one inert <script type="application/json"> data island per grc. A project with no graph-run-cases emits no <script> at all. Only the html output format is supported for the raw body (an unsupported --format is refused); a global machine --format wraps the HTML in the envelope. TO PUBLISH: the raw HTML goes to STDOUT, so redirect it to a file — lettuce board render --project P > board.html — and open that file. A machine --format (json/yaml) does NOT write a viewable page: it returns the HTML escaped inside the envelope as data.content, for a programmatic consumer that will unwrap it. Use board next to decide what to harden, board export for the data contract, and board render only when you want the page. The page states what board next states: a zero-cell project renders an UNSCOPED coverage section (never a completion line — with a DoD the conclusion names the empty frame instead of 'all scopes at bar', LET-465), a nil headline reads n/a in both meter branches (LET-1509), and with a declared grid a scope panel counts and draws only IN-grid cells — the same k/n as cell rollup, dod show, board export and board next — announcing any off-grid cells with lettuce grid scope show SCOPE instead of drawing them as grid rows (LET-531).
• Hosted (LET-1846): the server builds the board in the BACKGROUND (single-flight per domain, project and options, detached from the request, cached per writer generation, rebuilt after writes) and never inline, so a proxy timeout cannot cancel it. You get the board current at this generation, the LAST built board marked STALE while it rebuilds (a slightly old board still says what to work on), or 503 FW-API-READ-PENDING when none was built yet. The client waits for a pending build by default (polling with Retry-After, progress on stderr, up to --wait=DURATION, default 3m); --no-wait, or a spent budget, exits 8 (try again later, never 1). Provenance: one board: line on stderr in human formats (fresh | current | STALE + age); meta.read_kind, read_source, generation, computed_at, age_seconds, stale, current_generation, read_refresh in machine formats. An explicit --wait also waits out a stale board's rebuild.
• On an ARCHIVED project this read is refused with FW-READ-PROJECT-ARCHIVED (exit 1) unless --include-archived is passed; with it the result is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning and project_archived_at in the json/yaml data).

cell reconcile

Usage: lettuce cell reconcile [--dry-run] --project PROJECT

Reconcile STALE-GREEN cells: scan the project's stored cells and, for each in a guard-bite-gated done state (e.g. hardened) whose gate NO LONGER passes because its cited evidence broke (the cited task was deleted), machine-fire the active pack's regress transition so the stored state stops silently reading green (conformance §106: a gate-fail must regress, no silent stay-green). Detects a phantom with the exact evidence resolution the honest rollup uses, so reconcile and rollup agree; a cell whose gate still passes is untouched, making a second run a no-op. --dry-run reports what WOULD regress and writes nothing. It also rebuilds the cell side from the tickets alone and reports DECLARATION/CELL DRIFT (a ticket declares a coordinate with no cell, or an unparseable/unreadable declaration; LET-966 Gate 3). EXIT 1 when it reports any such drift (LET-1618) so a script can gate on a ticket/cell disagreement without parsing JSON — mirroring reconcile and graph-run-case conform; healing a stale-green phantom is a successful mutation and does not raise the code.

• kind: mutation
• output: collection — --format plain prints one cell reference (coordinate) per row of regressed; nothing when empty; its report findings announced on stderr
• exit codes: 0 success; 1 declaration/cell drift was found (LET-1618); any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --dry-run - Report which stale-green cells WOULD regress and write nothing.

Examples:

lettuce cell reconcile --project lettuce --author agent-1 --format json

lettuce cell reconcile --dry-run --project lettuce --format json

Notes:

• Available through both local and hosted backends. In hosted mode, --dry-run is an actorless GET read; a real reconciliation is an attributed POST mutation and requires --author. This project-wide command takes no coordinate and no --coords-file.

dimension list

Usage: lettuce dimension list --project PROJECT [--include-archived]

List a project's EFFECTIVE dimensions — the active convention pack's declared dimensions plus the project's additive runtime dimension layer (cells-v0.16 §4) — each tagged with its source (pack vs project). Read-only; the additive project layer never overrides pack vocabulary (decision A6).

• kind: read
• output: collection — --format plain prints one dimension reference (slug) per row of dimensions; nothing when empty
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: listing — proportional to the collection it reads once (paging or the task projection bound it)
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --include-archived - Read an ARCHIVED project on purpose: without this flag a read scoped to an archived project is refused (FW-READ-PROJECT-ARCHIVED); with it the read succeeds and is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning, and project_archived_at in the json/yaml data).

Examples:

lettuce dimension list --project lettuce --format json

lettuce dimension list --project lettuce --format plain

Notes:

• The effective dimension space is the active pack's dimensions (source=pack) plus any dimensions the project declared at runtime (source=project). Until a project declares runtime dimensions, every dimension is source=pack. REST parity: GET /v1/projects/{project}/dimensions.
• On an ARCHIVED project this read is refused with FW-READ-PROJECT-ARCHIVED (exit 1) unless --include-archived is passed; with it the result is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning and project_archived_at in the json/yaml data).

dimension show

Usage: lettuce dimension show SLUG --project PROJECT

Show ONE of a project's EFFECTIVE dimensions by slug — the resolved dimension (active convention pack ⊕ the project's additive runtime layer, cells-v0.16 §4/§8) with all its declared fields and its source (pack vs project). Read-only; an unknown slug is refused FW-CMD-USAGE.

• kind: read
• output: object — --format plain prints its dimension reference (slug)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: bounded — bounded by the objects it names, independent of the project's size
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Examples:

lettuce dimension show A --project lettuce --format json

lettuce dimension show A --project lettuce --format plain

Notes:

• Resolves against the same effective space dimension list enumerates: the active pack's dimensions (source=pack) first, then the project's runtime layer (source=project). A slug present in neither is refused FW-CMD-USAGE. REST parity: GET /v1/projects/{project}/dimensions/{slug}.
• On an ARCHIVED project this read is answered (the explicit reference is the explicit ask) and labelled ARCHIVED: an FW-READ-PROJECT-ARCHIVED-SHOWN warning (stderr in table/plain, warnings[] in json/yaml) and project_archived_at in the json/yaml data.

dimension member list

Usage: lettuce dimension member list DIMENSION --project PROJECT

List the members of ONE effective dimension — the base pack's enumerated members (source=pack, in declared order) plus any members the project's runtime layer added (source=project). Read-only; an open dimension that enumerates no members yields an empty list, and an unknown dimension is refused FW-CMD-USAGE.

• kind: read
• output: collection — --format plain prints one dimension-member reference (member) per row of members; nothing when empty
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: bounded — bounded by the objects it names, independent of the project's size
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Examples:

lettuce dimension member list A --project lettuce --format json

lettuce dimension member list A --project lettuce --format plain

Notes:

• member is a sub-noun under dimension (like cell evidence). Members are the base pack's declared members for a closed dimension (source=pack) plus any the project added at runtime (source=project); an OPEN dimension may also list members — its observed vocabulary (INT-100) — which never restrict its coordinates (only a closed dimension constrains a coordinate's member). REST parity: GET /v1/projects/{project}/dimensions/{dimension}/members.
• On an ARCHIVED project this read is answered (the explicit reference is the explicit ask) and labelled ARCHIVED: an FW-READ-PROJECT-ARCHIVED-SHOWN warning (stderr in table/plain, warnings[] in json/yaml) and project_archived_at in the json/yaml data.

dimension member add

Usage: lettuce dimension member add DIMENSION MEMBER [--name N] [--description D] [--rank R] [--attr K=V ...] --project PROJECT

Add a FIRST-CLASS member {slug,name,description,rank,attributes} to a project's runtime dimension (GA-1), recording a dimension-member-added event; the member's human name + order become visible everywhere the effective pack resolves (dimension member list, dimension show, board export axes[].members[]). Additive-only (decision A6): members can only be added to a PROJECT-declared dimension — a pack-declared dimension's members are fixed by the pack (refused FW-CMD-USAGE), and a member slug already enumerated by the dimension is refused (no duplicate). --name is the human label (empty renders as the slug); --rank orders members (rank 0 = unranked, sorts by slug); repeatable --attr declares first-class key=value data beyond name/description/rank (self-described-scopes Phase 1 — e.g. a scope member's shape/row_noun/stages), which the board export carries inline and a generic renderer reads from data.

• kind: mutation
• output: object — --format plain prints its dimension-member reference (member)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --name name - Human label for the member; defaults to rendering as the slug when omitted.
• --description text - Optional one-line description of the member (shown on hover in a board).
• --rank int - Optional integer sort order (ascending; rank 0 = unranked, falls back to slug order).
• --attr key=value - Optional repeatable first-class attribute declaration (key: lowercase-letter start then [a-z0-9_-], max 64). Carried inline on the board export; Phase-1 scopes use shape/row_noun/stages. Repeatable.

Examples:

lettuce dimension declare unit --family delivery --applicability universal --project lettuce --author agent-1 --format json

lettuce dimension member add unit task-set-where --name 'task set-where' --description 'Bulk-set a field on all matching tasks' --rank 210 --project lettuce --author agent-1 --format json

Notes:

• member add is a mutation under the dimension member sub-noun (like dimension declare). The dimension must be one the project DECLARED at runtime (source=project); adding to a pack dimension is refused FW-CMD-USAGE. The member slug is validated and must be unique within the dimension; every refusal happens BEFORE any write, so a refused add leaves NO partial member on disk. REST parity: POST /v1/projects/{project}/dimensions/{dimension}/members.

dimension member update

Usage: lettuce dimension member update DIMENSION MEMBER [--name N] [--description D] [--rank R] [--attr K=V ...] --project PROJECT

EDIT an existing first-class member's name/description/rank/attributes on a project's runtime dimension (Phase 0c), recording a dimension-member-updated event. A PARTIAL update touches only the fields you pass — updating just --rank leaves the name/description intact; a repeatable --attr sets/overwrites the named keys and leaves unmentioned attributes intact. The inverse-companion to dimension member add: add creates a member (refuses a duplicate), update edits one (refuses an ABSENT member, FW-PATH-NOT-FOUND). Additive-only (decision A6): only a member of a PROJECT-declared dimension is editable — a pack-declared dimension's members are fixed by the pack (refused FW-CMD-USAGE). At least one of --name/--description/--rank/--attr is required (FW-CMD-MISSING-ARGUMENT otherwise).

• kind: mutation
• output: object — --format plain prints its dimension-member reference (member)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --name name - New human label for the member (empty or whitespace-only clears it — renders as the slug).
• --description text - New one-line description of the member.
• --rank int - New integer sort order (ascending; rank 0 = unranked, falls back to slug order).
• --attr key=value - Optional repeatable first-class attribute to set/overwrite (unmentioned keys stay intact). Carried inline on the board export; Phase-1 scopes use shape/row_noun/stages. Repeatable.

Examples:

lettuce dimension declare unit --family delivery --applicability universal --project lettuce --author agent-1 --format json

lettuce dimension member add unit task-set-where --project lettuce --author agent-1 --format json

lettuce dimension member update unit task-set-where --rank 150 --project lettuce --author agent-1 --format json

lettuce dimension member update unit task-set-where --name 'Task set-where' --description 'Bulk-set a field on matching tasks' --project lettuce --author agent-1 --format json

Notes:

• member update is a mutation under the dimension member sub-noun (like dimension member add). The dimension must be one the project DECLARED at runtime (source=project); editing a pack dimension's member is refused FW-CMD-USAGE. The member MUST already exist — updating an absent member is refused FW-PATH-NOT-FOUND. Only the provided scalars change; every refusal happens BEFORE any write, so a refused update leaves the member UNCHANGED on disk. REST parity: PATCH /v1/projects/{project}/dimensions/{dimension}/members/{member}.

dimension declare

Usage: lettuce dimension declare SLUG --family FAMILY --applicability universal|conditional [--closed --member M ...] [--name N] [--description D] [--id ID] [--member-kind K] --project PROJECT

Author a project's runtime dimension in its additive layer (cells-v0.16 §4/§8), recording a dimension-declared event; the declared dimension becomes visible everywhere the effective pack resolves (cell set/show/rollup, board, query). Additive-only (decision A6): the slug must be UNIQUE against BOTH the active pack's dimensions AND the project's existing runtime dims — a runtime dimension can never shadow a pack dimension. A --closed dimension enumerates its members (repeatable --member); an open dimension may also list members (its observed vocabulary, the same state dimension member add reaches — INT-100), which never restrict its coordinates.

• kind: mutation
• output: object — --format plain prints its dimension reference (slug)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Flags:

• --family family - Family this dimension groups under; required, and must resolve to one of the active pack's declared families. Required.
• --applicability universal|conditional - Applicability class; required. universal = applies to every unit; conditional = applies only when a precondition holds. Required.
• --closed - Mark the dimension closed (its members are a fixed enumeration). Requires at least one --member.
• --member slug - A member (repeatable). Each must be a valid, distinct slug. On a --closed dimension the members are its fixed enumeration; on an open dimension they are its observed vocabulary and do not restrict coordinates. Repeatable.
• --name name - Human label for the dimension; defaults to the slug when omitted.
• --description text - Optional one-line description of what the dimension measures.
• --id id - Optional stable identifier for the dimension.
• --member-kind kind - Optional member value-kind (e.g. string or a typed entity reference).

Examples:

lettuce dimension declare deployment-readiness --family delivery --applicability conditional --project lettuce --author agent-1 --format json

Notes:

• The slug is validated (a valid single-path-component slug) and refused FW-CMD-USAGE if it collides with a pack dimension or a dimension the project already declared (additive-only, A6). --family must resolve to a pack-declared family; --applicability must be universal or conditional; a --closed dimension must enumerate at least one --member, and members must be distinct valid slugs (the same admission rule dimension member add crosses). Every refusal happens BEFORE any write, so a refused declare leaves NO partial dimension on disk. The dimension is born active. REST parity: POST /v1/projects/{project}/dimensions.

dimension rename

Usage: lettuce dimension rename OLD NEW --project PROJECT

Rename a project's RUNTIME dimension: move projects/PROJECT/dimensions/OLD to .../NEW preserving EVERYTHING inside (family, closed-ness, name, description, members and the dimension's own event ledger), RE-ADDRESS every cell whose coordinate names OLD (a coordinate IS the cell's identity, so each affected cell directory moves to its new coordinate hash carrying its whole aggregate — state, note, revision, its events ledger, and its evidence links with their asserted_at/asserted_rev provenance), rewrite every stored reference to the dimension and to the moved cells, and move every declared-grid column named after it (grid/scopes/<scope>/dims/OLD -> NEW, reported as grid_dims_renamed + grid_scopes; LET-1498). A whole-store structural migration like project rename/merge, applied atomically under the mutation lock. The lower-harm alternative to declaring a fresh dimension and recreating the cells, which would lose every cell event, both ledgers and all evidence provenance.

• kind: mutation
• output: object — --format plain prints its dimension reference (new_dimension)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Examples:

lettuce dimension rename unit coverage-unit --project lettuce --author agent-1 --format json

Notes:

• OLD and NEW are POSITIONAL slug arguments (not --project). Only a dimension the project DECLARED is renameable — a pack-bundled dimension is compiled into the binary, so naming one is refused FW-PATH-NOT-FOUND. Refuses if NEW is already declared by the project or the active pack (a collision, FW-CMD-USAGE, additive-only A6) or is an invalid slug (FW-NAME-SLUG). REFUSES with FW-DIMENSION-RENAME-CONFLICT when the renamed coordinates cannot coexist: two cells collapsing onto one coordinate, a coordinate that would name one dimension twice, or one that would assert the reserved scope=unscoped bucket. REFUSES with FW-DIMENSION-RENAME-UNSAFE, writing nothing, for a reference it cannot rewrite: one folded into a CONTENT-ADDRESSED identity (a graph-run-case advance event or a carrier directory is named by the hash of its own payload), a stored saved-query FQL naming the dimension (the FQL cells source projects scope/unit/dim/group/kind as fixed columns, so no rewrite can re-point the query), a move off/onto a reserved coordinate axis the project's DECLARED grid or DoD keys off, or a grid column it cannot carry without moving a denominator (NEW is already a column of that scope, or stored cells file under the column as dim=OLD and would be stranded off-grid). Prose is never rewritten, so the dimension-declared event's reason slot keeps the slug the dimension was declared under — an append-only ledger records what happened. On any failure the store is left byte-unchanged (atomic). Verify after with lettuce validate --strict. REST parity: POST /v1/projects/{project}/dimensions/{old}/rename. PREREQUISITE for the example above: OLD (here, unit) must already be a project-declared dimension — lettuce dimension declare unit --family FAMILY --applicability universal|conditional --project lettuce --author agent-1 --format json.

dimension close

Usage: lettuce dimension close DIMENSION --project PROJECT

CLOSE a project's runtime dimension: flip its closed flag from false to true so the coordinate validator begins ENFORCING declare-before-use on that axis. From here on a cell set naming a member the dimension does not enumerate is refused instead of silently minting it — which is the whole point, since a coordinate is the cell's identity and a typo mints a NEW cell rather than editing the intended one. Enforcement and its refusal already existed; this is the transition into it that no command previously offered (declare is additive-only and refuses an existing slug, rename re-addresses, and member add/update never touch closed). CLOSED MEANS DECLARE-BEFORE-USE, NOT FROZEN: a new member can be added with dimension member add at any time and is usable immediately.

• kind: mutation
• output: object — --format plain prints its dimension reference (dimension)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Examples:

lettuce dimension declare unit --family delivery --applicability universal --project lettuce --author agent-1 --format json

lettuce dimension member add unit task-set-where --project lettuce --author agent-1 --format json

lettuce dimension close unit --project lettuce --author agent-1 --format json

Notes:

• DIMENSION is a POSITIONAL slug argument. Only a PROJECT-declared dimension is closable; the bundled pack's dimensions carry uppercase slugs, which the slug grammar refuses (FW-NAME-SLUG) before the pack-declared check is ever reached. REFUSES, writing nothing, when: the dimension is already closed (FW-CMD-USAGE naming the current state — a second close is an error, not a silent no-op); it enumerates NO members (mirroring declare --closed, which requires at least one); or — the gate that makes this safe to run against a live store — any member OBSERVED in a stored cell's coordinate on that axis is not declared. That last refusal NAMES the undeclared members in its actual slot, because closing then would start refusing coordinates that are valid today. The coverage gate reads the CELLS, not the registry: a registry-only check confirms the declared members are declared and stays blind to the ones the store actually uses. The result echoes cells_scanned so the no-op claim is checkable rather than asserted. There is deliberately no re-open counterpart: closing is the transition coordinate-integrity work needs, and an un-close would need its own coverage story. REST parity: POST /v1/projects/{project}/dimensions/{dimension}/close.

lettuce command group Core And Runtime — 18 commands. Generated from lettuce usage --format okf (always in sync with the binary).

Back to Command Reference.

Commands in this group

• usage
• skill
• docs
• docs list
• docs show
• docs export
• okf
• version
• self-update
• init
• status
• agents
• work
• validate
• doctor
• recover
• cleanup
• reconcile

---

Initialize stores, inspect runtime health, validate data, recover locks, clean runtime state, and print usage.

usage

Usage: lettuce usage [command-prefix] [--format table|plain|json|yaml|markdown|okf] [--out DIR]

Print complete CLI usage documentation for humans and agents. --format okf --out DIR emits the OKF command-reference bundle regenerated by 'make docs'.

• kind: local
• output: content — --format plain prints the content, as table prints it
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: false
• requires project: false
• requires author: false
• stable snapshot: false
• idempotency key: false

Flags:

• --out dir - Destination directory for the OKF command-reference bundle (only with --format okf). A file lettuce usage generated there is regenerated; any other file of the same name is refused FW-PATH-EXISTS before anything is written (LET-1972).

Examples:

lettuce usage --format markdown

lettuce usage query saved --format json

lettuce usage --format okf

Notes:

• Does not require an initialized store.
• Add --out DIR with --format okf to write the command-reference bundle (this is what 'make docs' runs); without --out it streams the bundle as a single document to stdout.

skill

Usage: lettuce skill

Print the embedded SKILL.md agent guide (also served at / and /SKILL.md by serve).

• kind: local
• output: content — --format plain prints the content, as table prints it
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: false
• requires project: false
• requires author: false
• stable snapshot: false
• idempotency key: false

Examples:

lettuce skill

lettuce skill --format json

Notes:

• Does not require an initialized store.

docs

Usage: lettuce docs

Print the embedded, build-fresh wiki as the self-contained HTML explorer (pipe it to a file and open it in a browser). Its verbs are separate commands: 'docs list' ENUMERATES every concept id, 'docs show CONCEPT' streams one concept, 'docs export --out DIR' writes the artifacts for an agent. Also served at /docs and /docs/flat.md by serve.

• kind: local
• output: content — --format plain prints the content, as table prints it
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: false
• requires project: false
• requires author: false
• stable snapshot: false
• idempotency key: false

Examples:

lettuce docs

lettuce docs --format json

Notes:

• Does not require an initialized store. The wiki is regenerated by 'make docs' and embedded in the binary.
• --out belongs to 'docs export': typed on bare docs it is refused FW-CMD-USAGE with the export command to run instead (LET-1973).

docs list

Usage: lettuce docs list

ENUMERATE every concept id of the embedded wiki: one per line for humans, a {concepts,count} envelope for machines. docs list and docs show resolve against the SAME conceptIDs source, so the list can never advertise a concept show rejects (LET-1001: concept was an enumerable noun whose only positive discovery path was provoking a refusal and reading its expected field).

• kind: local
• output: collection — --format plain prints one concept reference (the row itself) per row of concepts; nothing when empty
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: false
• requires project: false
• requires author: false
• stable snapshot: false
• idempotency key: false

Examples:

lettuce docs list

lettuce docs list --format json

Notes:

• Does not require an initialized store.

docs show

Usage: lettuce docs show CONCEPT

Stream one concept of the embedded wiki (frontmatter + body) as markdown. CONCEPT is the full bundle id (concepts/concept-task), its basename (concept-task) or a unique suffix; docs list enumerates them. An unknown CONCEPT is refused FW-REF-MISSING-CONCEPT, which lists the valid ids.

• kind: local
• output: content — --format plain prints the content, as table prints it
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: false
• requires project: false
• requires author: false
• stable snapshot: false
• idempotency key: false

Examples:

lettuce docs show concept-task

lettuce docs show reference/cmd-tasks

Notes:

• Does not require an initialized store.

docs export

Usage: lettuce docs export --out DIR

Write the embedded wiki artifacts (wiki.html + wiki-flat.md) into DIR for an agent to read offline.

• kind: local
• output: object — --format plain prints its docs-export reference (out)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: false
• requires project: false
• requires author: false
• stable snapshot: false
• idempotency key: false

Flags:

• --out dir - The directory to write wiki.html and wiki-flat.md into, created if missing. An earlier docs export there is replaced; any other file of those names is refused FW-PATH-EXISTS before anything is written (LET-1972). Required.

Examples:

lettuce docs export --out /tmp/lettuce-wiki

Notes:

• Does not require an initialized store.

okf

Usage: lettuce okf <okf-command> [args...] | lettuce okf docs <okf-command> [flags...]

Mount the embeddable okf CLI as a subcommand: lettuce okf validate ./bundle behaves exactly like okf validate ./bundle. The mount forwards EVERY okf command, mutating ones included — e.g. validate, lint, render (--site), export, graph, search alongside init, apply, page, move; this is a PARTIAL example, so run lettuce okf help for the full command set. lettuce okf docs <okf-command> runs the okf command against lettuce's OWN embedded wiki bundle (docs/wiki, compiled into the binary) — e.g. lettuce okf docs render --site ./site writes a single self-contained navigable HTML site of lettuce's documentation with no files on disk and no network.

• kind: local
• output: content — --format plain prints the content, as table prints it
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: false
• requires project: false
• requires author: false
• stable snapshot: false
• idempotency key: false

Examples:

lettuce okf version

lettuce okf docs validate

lettuce okf docs lint

lettuce okf help

Notes:

• Does not require an initialized store. Delegates to okf's embeddable pkg/okf facade; okf is vendor-neutral and fully offline. lettuce okf docs appends lettuce's materialized embedded-wiki bundle root as the trailing positional and passes every other flag through verbatim. Point okf at an arbitrary bundle with lettuce okf validate ./bundle or lettuce okf render --site ./out ./bundle (a bundle path / output dir the examples census does not fabricate, so those forms are shown here rather than auto-executed).

version

Usage: lettuce version

Print the lettuce binary version.

• kind: local
• output: report — --format plain prints the table bytes
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: false
• requires project: false
• requires author: false
• stable snapshot: false
• idempotency key: false

Examples:

lettuce version --format json

lettuce version --format plain

self-update

Usage: lettuce self-update [--check | --dry-run]

Install the lettuce client release the bound server runs, in place (LET-1932). The server serves the client binaries of its own build (GET /v1/client/{os}-{arch} and .sha256, any role), so a lettuce token is all it needs — no GitHub access. It downloads the binary for this platform, verifies its sha256 against the server's checksum, runs the new binary's version to prove it runs here and reports the server's release, then replaces this executable ATOMICALLY (a temporary file beside it, flushed, renamed over it). This is FW-CLIENT-VERSION-SKEW's and FW-CLIENT-TOO-OLD's first suggested action.

• kind: server
• output: report — --format plain prints the table bytes
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: false
• requires project: false
• requires author: false
• stable snapshot: false
• idempotency key: false

Flags:

• --check - Report only: this binary's version, the server's, whether the server serves a binary for this platform and whether this executable may be replaced here. Downloads and changes nothing.
• --dry-run - Download, verify the checksum and prove the new binary runs, then discard it: everything except the replace.

Examples:

lettuce self-update --check --format json

lettuce self-update --dry-run

lettuce self-update --format json

Notes:

• Refusals (nothing is replaced): FW-SELF-UPDATE-CHECKSUM-MISMATCH (the download does not match the server's checksum), FW-SELF-UPDATE-PATH-NOT-WRITABLE (the executable is not owned by you in a directory you can write, or this runs under sudo — self-update never escalates), FW-SELF-UPDATE-VERIFY-FAILED (the new binary did not run here or did not report the server's release), FW-CLIENT-BINARY-UNAVAILABLE (the server has no binary of its own release for this platform; fall back to SKILL.md §0.1). A crash between the write and the rename leaves the old binary in place; the next run removes the leftover temporary file (.lettuce-self-update-<pid>-*) of a process that is gone.
• Symlinks are resolved: the real file behind lettuce on PATH is replaced. The server and bearer come from the usual client binding (pointer, --server-url, LETTUCE_BEARER_FILE); the domain does not change the binary. Status values: up-to-date, update-available (--check), would-update (--dry-run), updated. Needs a hosted store; locally it is refused FW-CMD-USAGE.

init

Usage: lettuce init [--author AUTHOR] [--bootstrap-project PROJECT] [--bootstrap-author] [--idempotent] [--yes] [--force] [--legacy-root PATH]

Create a store root skeleton and optionally create a root author and bootstrap project.

• kind: mutation
• output: object — --format plain prints its store reference (root)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: false
• stable snapshot: false
• idempotency key: true
• external input keys (these go INSIDE data, not at the top level): bootstrap_project, bootstrap_author, idempotent
• external input envelope: {"schema_version":"v0.16","kind":"lettuce-command-input","data":{ ...command fields... }}

Flags:

• --author author - Root author to create or use for bootstrap project.
• --bootstrap-project project - Create one project during initialization.
• --bootstrap-author - Create/link the bootstrap author when needed.
• --idempotent - Treat existing initialized state as success when valid.
• --yes - Confirm that --bootstrap-project may add an ADDITIONAL project to a store that already holds one (without it, init skips an absent bootstrap project there).
• --force - Alias of --yes: confirm an additional project.
• --legacy-root path - Store-root cutover guard (local only): the store root this --root replaces. The Helm chart passes persistence.storeRoot when initializing <domainsRoot>/default, and <domainsRoot>/default when initializing storeRoot with domains disabled (a rollback). init refuses with FW-DOMAIN-CUTOVER-PENDING, writing nothing, while PATH still holds an initialized store and --root does not, while both hold one, or when --root holds a whole store nested one level down.

Examples:

lettuce init --root .lettuce --author agent-1 --bootstrap-project lettuce --bootstrap-author --idempotent --format json

Notes:

• --bootstrap-project creates the project only while init creates the store (the store holds no project yet). On a store that already holds a project, an absent bootstrap project is SKIPPED: init writes nothing, exits 0 and warns FW-PROJECT-BOOTSTRAP-SKIPPED (LET-1878; the Helm init container runs this on every pod start, so a deleted or moved bootstrap project must never crash-loop it). Pass --yes (or --force) to add it there anyway; over HTTP send "confirm": true in the POST /v1/init body. The first project of a fresh store never needs it.
• --legacy-root is the guard that keeps a domains upgrade from bootstrapping a silent EMPTY default domain over a store that was not moved yet; the cutover procedure is docs/operations/PVC-CUTOVER-RUNBOOK.md §8.
• An --idempotent re-run that would write nothing (initialized store, the author present, and the bootstrap project present or skipped) takes no store lock and is not refused by a stranded writer (FW-RUNTIME-WRITER-ACTIVE), e.g. the lock a replaced pod left: the Helm init container runs exactly this on every pod start, and serve's startup recovery is what reclaims that lock (LET-1826). The project-scoped consistency gate still applies; an init that would write stays fully gated.

status

Usage: lettuce status [--full]

Report store validity, runtime state, Git state, and capability flags — GRAMMAR + runtime/Git state only. It does NOT run the doctor probes (terminal-lease, workflow-policy, graph-run-case, completion-gate), so a clean status is not a clean probe verdict; run lettuce doctor --format json for those.

• kind: read
• output: report — --format plain prints the table bytes
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: listing — proportional to the collection it reads once (paging or the task projection bound it)
• requires root: true
• requires project: false
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --full - List EVERY retained runtime operation record in runtime.operations (LET-2003). By default status lists the open (not released) records and the newest 20, and runtime.operations_summary counts the rest (retained, open, listed, truncated): released records are kept until the runtime cleanup removes them, and listing thousands of them made status time out on a hosted store.

Examples:

lettuce status --root . --format json

lettuce status --root . --format plain

lettuce status --full --format json

Notes:

• status is the CHEAP health check: it must not pay a whole-store scan, and the doctor probes (e.g. the terminal-lease sweep over every project) would. The operator ruling that reads "Doctor/status can show current issues" is therefore satisfied by doctor for these findings; lease list --task-terminal is the categorical form of the terminal-lease one. This boundary is deliberate (LET-1628), not an omission.
• data.connection says which store this invocation reached: {"backend":"local"} locally; in client mode also server (endpoint, never a token), server_version, client_version, the EFFECTIVE domain and domain_source (flag|env|pointer|token-default), project (the resolved project name, omitted when none is bound), project_source (flag|env|pointer|store-url) and project_exists (omitted when no project is bound or it could not be checked). A bound project that does not exist in the effective domain adds an FW-REF-MISSING-PROJECT WARNING naming the domain selectors — the silent wrong-domain case.
• data.capabilities.output_formats lists every value --format accepts, and data.capabilities.format_support says per format whether it is a machine envelope, which commands it is scoped to, and whether other commands refuse it (exclusive). Both are derived from the same catalog the --format parser and the per-command format gates read, so an advertised format is always an accepted one (LET-331).

agents

Usage: lettuce agents --project PROJECT [--format table|plain|json|yaml] [--include-archived] [--wait[=DURATION] | --no-wait]

The actor roster: every identity (author) seen in the project with the last time they acted, what they last did (last event kind + target), their event count, and how many ACTIVE leases they hold. Read-only; folds the same per-object ledgers query timeline merges plus the active leases. Use it to avoid reusing an existing name and to see who is around.

• kind: read
• output: collection — --format plain prints one author reference (name) per row of agents; nothing when empty
• exit codes: 0 success; 8 hosted result not ready yet (FW-API-HEALTH-PENDING / FW-API-READ-PENDING): retry later or --wait; not a finding; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: project — walks the whole project: on a hosted server a background build (--wait[=DURATION] / --no-wait; exit 8 while it is pending)
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --include-archived - Read an ARCHIVED project on purpose: without this flag a read scoped to an archived project is refused (FW-READ-PROJECT-ARCHIVED); with it the read succeeds and is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning, and project_archived_at in the json/yaml data).
• --wait duration - Hosted only (LET-2003): this read is a server-owned background build; wait for a pending build up to DURATION (default 3m0s; a bare --wait also waits out a STALE answer's rebuild), printing progress on stderr. Exit 8 when the budget ends with the build still pending. Locally the flag is accepted and inert.
• --no-wait - Hosted only (LET-2003): do not wait for a pending build; exit 8 at once (the build keeps running). Locally inert.

Examples:

lettuce agents --project lettuce --format json

lettuce agents --project lettuce

Notes:

• On an ARCHIVED project this read is refused with FW-READ-PROJECT-ARCHIVED (exit 1) unless --include-archived is passed; with it the result is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning and project_archived_at in the json/yaml data).

work

Usage: lettuce work --project PROJECT [--format table|plain|json|yaml] [--include-archived]

The single global coordination view: what is IN FLIGHT (and who holds it), what NEEDS HELP (blocked / needs-human, or a stale EXPIRED lease that can be taken over), and what is AVAILABLE (no active lease). Read-only; composes the same task + lease reads task list and lease list expose, so it cannot disagree with them. Terminal tasks are excluded and archived tasks are hidden.

• kind: read
• output: report — --format plain prints the table bytes
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: listing — proportional to the collection it reads once (paging or the task projection bound it)
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --include-archived - Read an ARCHIVED project on purpose: without this flag a read scoped to an archived project is refused (FW-READ-PROJECT-ARCHIVED); with it the read succeeds and is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning, and project_archived_at in the json/yaml data).

Examples:

lettuce work --project lettuce --format json

lettuce work --project lettuce

Notes:

• On an ARCHIVED project this read is refused with FW-READ-PROJECT-ARCHIVED (exit 1) unless --include-archived is passed; with it the result is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning and project_archived_at in the json/yaml data).

validate

Usage: lettuce validate [--scope store|project|task|runtime] [--task REF] [--strict|--loose] [--wait[=DURATION]] [--project PROJECT]

Validate canonical store or runtime state against the on-disk grammar. NOT the strictest available check, despite --strict: doctor runs this SAME validation plus a derived-divergence probe, so a store this reports clean can still be damaged (forged derived scalars, merge conflicts, ladder-overlay drift). Prefer doctor as a CI gate; use validate for a fast structural check.

• kind: read
• output: report — --format plain prints the table bytes
• exit codes: 0 success; 1 the store is invalid: the report (ok:true) lists the findings; 8 hosted result not ready yet (FW-API-HEALTH-PENDING / FW-API-READ-PENDING): retry later or --wait; not a finding; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: store — walks the whole store: on a hosted server a background health job (--wait[=DURATION]; exit 8 while it is pending)
• requires root: true
• requires project: false
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --scope scope - Validation scope. Defaults to project when an explicit --project is given, else store. --scope store validates EVERY project even when --project is also set.
• --project project - Project context. With no --scope it implies --scope project (validate ONLY that project) — the form a project agent on a shared multi-tenant server should use. An explicit --scope always wins.
• --task task-ref - Task reference for task scope.
• --strict - Strictest user-facing GRAMMAR check — but NOT a superset of doctor (LET-1723): --strict is silent on derived-divergence drift (forged/hand-edited derived scalars, merge conflicts, ladder-overlay drift) AND on graph-run-case CONFORMANCE (LET-1823, LET-1212 checker contract) — whether a run-case's advance history matches a replay of its graph-def is doctor's (DoctorGraphRunCaseProbe) and graph-run-case conform's judgment alone, never validate's. So it can exit 0 on a store doctor exits nonzero on with FW-STORE-DERIVED-DRIFT or a non-conforming run-case. Do not gate CI on validate --strict expecting a health verdict; run doctor for that.
• --loose - Inspection mode. Core filesystem integrity remains enforced.
• --wait - Hosted stores only (LET-1835 phase 2): written --wait or --wait=DURATION (default 30m). Poll a pending (FW-API-HEALTH-PENDING) or stale-with-refresh-running report with the server's Retry-After until a current one is ready or the budget ends; progress on stderr. Without it a pending report exits 8 at once. No effect locally.

Examples:

lettuce validate --scope store --strict --format json

lettuce validate --project lettuce --loose --format json

Notes:

• Hosted (ADR-0022, LET-1835): every scope except runtime is an admin-only, single-flight, server-owned background scan cached per writer generation, exactly like doctor: never run inline, the last report served marked stale while a refresh runs, FW-API-HEALTH-PENDING (exit 8) while none exists; the envelope carries meta.health_source (fresh|cached), meta.generation, meta.computed_at, meta.age_seconds and meta.stale. --scope runtime stays a cheap reader call. Readers use lettuce doctor --summary.

doctor

Usage: lettuce doctor [--shallow | --summary] [--wait[=DURATION]] [--project PROJECT] [--format table|plain|json|yaml|markdown]

Run validation plus a read-only derived-divergence probe (detects forged derived scalars, merge conflicts, ladder-overlay drift, and graph-run-case conformance judged against the pre-enforcement landmark (LET-1823) — none of which grammar validation computes, by the LET-1212 checker contract) with LLM-friendly explanations and repair suggestions. --shallow skips the probe for performance. Against a hosted server (ADR-0022) the scan is a server-owned background job (admin-only, single-flight, cached per writer generation) that a request never runs inline: you get the report current at this generation, the last completed report marked stale while a refresh runs, or FW-API-HEALTH-PENDING (exit 8, try again later; --wait polls); --summary reads the server's last computed health instead and never scans.

• kind: read
• output: report — --format plain prints the table bytes
• exit codes: 0 success; 1 findings: the store is not healthy (ok:true report); 8 hosted result not ready yet (FW-API-HEALTH-PENDING / FW-API-READ-PENDING): retry later or --wait; not a finding; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: store — walks the whole store: on a hosted server a background health job (--wait[=DURATION]; exit 8 while it is pending)
• requires root: true
• requires project: false
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --shallow - Skip the read-only derived-divergence probe and run grammar/structure validation only (faster; use when only the fast checks are needed).
• --project project - Scope the health report to ONE project: its grammar pass plus only the probe findings under projects/PROJECT, so a project agent is not handed repair suggestions for data it does not own. Omit it to diagnose the whole store (the repo-local owner's CI gate).
• --summary - Hosted stores only (LET-1835): print the server's LAST COMPUTED health for the domain (GET /v1/health/domain: status, counts by code, generation, age, whether each record is current) without starting a scan. Reader role. Always exits 0 on success: it reports recorded health and is never a gate; run lettuce doctor (admin) for a verdict.
• --wait - Hosted stores only (LET-1835 phase 2): written --wait or --wait=DURATION (default 30m). While the server answers FW-API-HEALTH-PENDING (no report yet) or serves a STALE report whose refresh is running, poll with the server's Retry-After until a current report is ready or the budget ends; progress goes to stderr. Without it a pending report exits 8 at once. No effect locally (the local scan is the wait).

Examples:

lettuce doctor --format json

lettuce doctor --project lettuce --format json

lettuce doctor --shallow --format markdown

lettuce doctor --summary --format json

Notes:

• Hosted (ADR-0022): GET /v1/doctor and GET /v1/validate (except --scope runtime) require the admin role; a project-scoped grant may scan only its project. Scans are server-owned background jobs (phase 2): a request waits at most a few seconds, never runs the scan inline, and a disconnect never cancels one. Concurrent requests for the same report join one scan, a repeat at the same writer generation is served from cache, and after a write the LAST report is served marked stale while a refresh runs. The envelope says which: meta.health_source (fresh|cached), meta.generation, meta.computed_at, meta.age_seconds, meta.stale (+ meta.current_generation and meta.health_refresh: queued|running|rate-limited|busy), meta.health_joined when it joined a running scan; human output prints one health: line (STALE when stale). With no report yet the server answers 503 FW-API-HEALTH-PENDING with Retry-After and the job's progress: the CLI prints not ready yet and exits 8 (not a finding); --wait polls. A full scan queue answers 503 FW-API-HEALTH-SCAN-BUSY and a spent hourly scan budget 429 FW-API-HEALTH-SCAN-RATE-LIMITED, both with Retry-After (with a stale report to serve, the report is served instead). Cached health is never a gate. Hosted doctor skips the local-only git and runtime-skeleton families and lists them in not_applicable.

recover

Usage: lettuce recover [--abandon | --report-only]

Inspect runtime operations and recover safe interrupted mutations. Resolves a stuck active/failed recovery attempt so blocked mutations proceed. Use --abandon to force-clear an orphaned active operation, write lock, or in-progress idempotency claim whose owner cannot be proven dead (another host, no usable pid, or a pid owned by another user); a provably-alive idempotency claimant is never touched. Without --abandon recover completes or reclaims an idempotency claim only when its claimant is provably dead on this host (LET-592). NOT RECLAIMED BY DESIGN (LET-1226): an operation left in a spec §17.2 non-terminal WRITE PHASE (preparing, writing, validating, committing) by a provably dead owner is reported and deliberately left in place, because a writer that died mid-write may have left a partially-written canonical file and the phase marker is the only evidence that happened — clearing it would destroy exactly what an operator needs to investigate. recover emits FW-RUNTIME-WRITE-PHASE-STRANDED naming each such record (doctor reports the same); run validate --strict to check the objects it was writing. Once recover has SETTLED an interrupted create such a record names (rolled it back, or found it committed) in a store that validates, it keeps the record but marks it settled (settled_by, settled_at, settlement — LET-1966): the warning stops on recover and doctor, and the record never again proves a directory's create never committed. An interrupted create (a task, comment, saved-query, graph-def, registry-object, run, dimension, project state/gate/transition, carrier or graph-run-case directory whose commit marker never landed) is finished from its ledger or rolled back ONLY when the directory holds nothing beyond the create and the create is proven never committed (the dead create's operation record names that exact directory: task create, comment add, query saved create, graph-def create, registry create, run start, dimension declare, defaults state|gate|transition declare, carrier produce or graph-run-case open — a record naming only its parent or a sibling proves nothing — AND that record wrote THIS object: its operation id is the operation-id the object's own create recorded, which every create writes first, or the directory is empty; a stale record naming an object created again at the same path proves nothing, LET-2001); a directory the store's committed ledger records (committed history beyond its create, its commit marker, a create event committed by its marker or passed through by the owner's committed revision chain, a reply naming a comment) is KEPT and reported as FW-RUNTIME-RECOVERY-OBJECT-KEPT with the markers to restore, an event the committed chain passes through or whose own revision-after is present is never discarded or reverted, even below a lowered revision (b32, b37). Recover never deletes and then refuses (b37): every removal or lowering it makes is held in its undo journal (.runtime/recovery-undo) until the verdict, so a pass that ends with the store still invalid removes nothing and reports each undone removal as kept; a pass that died before its verdict is undone by the next. Use --report-only (LET-1533) to INSPECT without changing anything: three refusals (FW-RUNTIME-WRITER-ACTIVE, the interrupted-evidence advisory, and the lock advisory) tell an operator to "run lettuce recover to inspect", and until that flag existed there was no way to do so — a plain recover reaps released operation records, heals forward, quarantines foreign runtime directories and may reset the generation. --report-only takes no lock, writes nothing, and reports what a real recover WOULD reclaim, using the same released-state predicate the reaper uses so the preview cannot promise what the apply declines. It also lists, in warnings[], each orphaned idempotency claim (FW-RUNTIME-IDEMPOTENCY-ORPHANED, LET-1776), each active operation record missing from the open-operation index (FW-RUNTIME-OPEN-OPERATION-UNINDEXED, LET-1775) and each leftover recovery undo journal of a recover pass that died before its verdict, with the number of changes it holds (FW-RUNTIME-RECOVERY-UNDO-PENDING, LET-1993) — the same findings doctor reports — since recover acts on all three. It is also the affordable form: a normal recover pays a whole-store validation (61.4s of CPU on lettuce's own store) whose diagnostics only the heal passes consume, while the report reads the runtime scope alone. Mutually exclusive with --abandon, which forces a reclamation.

• kind: maintenance
• output: report — --format plain prints the table bytes
• exit codes: 0 success; 1 the canonical store is still invalid after recovery; 6 the store still needs recovery (a present writer lock, an active operation or an unfinished recovery); any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: false
• stable snapshot: false
• idempotency key: false

Flags:

• --abandon - Force-clear an orphaned active operation, write lock, or in-progress idempotency claim whose owner liveness is undeterminable.
• --report-only - Inspect without writing: report what recover WOULD reclaim (including orphaned idempotency claims, unindexed active operations and leftover recovery undo journals with their change counts, in warnings[]), taking no lock and changing nothing. Mutually exclusive with --abandon.

Examples:

lettuce recover --author operator --format json

lettuce recover --report-only --format json

lettuce recover --abandon --author operator --format json

Notes:

• May mutate runtime and recovery state.

cleanup

Usage: lettuce cleanup

Remove released runtime operation data and expired idempotency-key records without changing canonical files.

• kind: maintenance
• output: report — --format plain prints the table bytes
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: false
• requires author: false
• stable snapshot: false
• idempotency key: false

Examples:

lettuce cleanup --format json

reconcile

Usage: lettuce reconcile --project PROJECT [--dry-run|--apply]

Store-merge-healing: scan a project for derived state that diverged from its event log (the shape a blind git merge leaves) and, with --apply, heal the deterministically-recomputable Class-A divergences (cell revision/state/note, task revision/status, field-set and custom-field values, run status/timing, comment status, saved-query status, registry object fields, dimension active, graph-run-case revision/state, graph-def revision, and the archived-at markers of tasks, comments, artifacts and the project itself) under the write lock. It also reports (never rewrites) an artifact whose payload files no longer match the content-hash its own creation/replacement event recorded (LET-1263). Dry-run report is the default; --apply requires an author and mutates. Class-B conflicts — a genuine fork rather than a lagging scalar (e.g. a broken revision-chain, cell evidence/confirmation counts, a graph-run-case whose value/coordinate diverged, or an UNEXPLAINED task or registry scalar that neither the create-time fields record nor any field-set / registry-update event accounts for — LET-440, LET-1797) — are reported, never rewritten.

• kind: maintenance
• output: report — --format plain prints the table bytes
• exit codes: 0 success; 1 unresolved Class-B conflicts remain (ok:true report); any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: false
• idempotency key: false

Flags:

• --dry-run - Report divergences without writing (the default).
• --apply - Heal Class-A divergences under the write lock (requires --author).

Examples:

lettuce reconcile --project lettuce --format json

lettuce reconcile --project lettuce --apply --author agent-1 --format json

Notes:

• Distinct from cell reconcile (which re-derives cell grades against the pack); this checks derived==f(events) coherence across cells, tasks, runs, comments, saved-queries, registry objects, dimensions, graph-run-cases, graph-defs, and every archive marker. Exit 1 when unresolved Class-B conflicts remain. Every conflict reports the diverged stored/expected; a revision-chain fork additionally names forked_at_revision, the colliding_events that both consumed it (id, author, kind, at, revision pair) and a suggested_actions repair path — for a class that is deliberately never rewritten, the report is the entire deliverable.
• An unexplained task scalar (LET-440: a phantom a blind merge kept, a hand-edited title) is reported with suggested actions that record the intended value with task set/task unset/custom set/custom clear, which the mutation path deliberately does not block on this finding. Tasks created before the create-time fields record existed are EXEMPT and reported only as the count unrecorded_create_fields (human output: an exempt N task(s) line), never as conflicts.
• An unexplained registry scalar (LET-1797: the registry analog of LET-440 — a phantom a blind merge kept, a hand-edited title/status/color/owner/due-at/rank/stage/confidence/value-kind/required) is reported the same way, with suggested actions naming registry update KIND SLUG --FIELD VALUE. Registry objects created before the create-time fields record existed are EXEMPT and reported only as the count unrecorded_registry_create_fields (human output: an exempt N registry object(s) line), never as conflicts.
• An artifact blob mismatch (LET-1263, MH-8's unbuilt third clause) is reported as a Class-B conflict with field content-hash, stored the digest of the live payload manifest (every file under files/, one <sha256> <path> line each in sorted path order) and expected the digest its own creation/replacement event recorded — never rewritten, since there is no safe automatic repair for corrupted binary content. It covers every payload file (a changed, added, removed or renamed file all diverge); validate --strict still names the individual file whose checksums/ entry disagrees. Artifacts created before the content-hash record existed are EXEMPT and reported only as the count unrecorded_artifact_content_hashes (human output: an exempt N artifact(s) line), never as conflicts.

lettuce command group Coverage Grid — 6 commands. Generated from lettuce usage --format okf (always in sync with the binary).

Back to Command Reference.

Commands in this group

• grid scope add-unit
• grid scope add-dim
• grid scope remove-unit
• grid scope remove-dim
• grid scope show
• grid show

---

Declare a project's per-scope coverage GRID (implicit cells, cells-v0.16 §A2): the units (rows) and applicable dims (cols) whose cross-product is the honest coverage denominator. Declare the grid once and every un-worked coordinate counts as implicit-untested — record real progress instead of minting cells one by one.

grid scope add-unit

Usage: lettuce grid scope add-unit SCOPE UNIT... --project PROJECT

Declare unit (row) members on a scope's grid — the things being covered under that scope (cells-v0.16 §A2). Records a project-updated event; each member slug is validated (a valid single-path-component slug) and refused FW-CMD-USAGE otherwise, BEFORE any write. Idempotent: a member already declared is a no-op. Once units AND applicable dims are declared, the scope's honest denominator is |units|×|dims| and every un-worked coordinate reads implicit-untested in rollup/board/dod.

• kind: mutation
• output: object — --format plain prints its grid-scope reference (scope)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Examples:

lettuce grid scope add-unit s1 validate recover reconcile --project lettuce --author agent-1 --format json

Notes:

• Members are additive marker declarations under projects/<p>/grid/scopes/<scope>/units/<member>; storage stays sparse (only asserted cells are stored) while the denominator counts the declared grid. A malformed slug is refused before any write, so a refused add leaves nothing on disk. REST parity: declared over HTTP via POST /v1/projects/<p>/grid/scopes/<scope>/units — CLI local and client mode land the same project-updated event (differential parity guarded).

grid scope add-dim

Usage: lettuce grid scope add-dim SCOPE DIM... --project PROJECT

Declare applicable dimension (col) members on a scope's grid — the coverage dimensions that apply to that scope (cells-v0.16 §A2). Records a project-updated event; each slug is validated and refused FW-CMD-USAGE otherwise, BEFORE any write. Idempotent. Together with the scope's units, the applicable dims define the declared applicable space |units|×|dims| that becomes the honest coverage denominator.

• kind: mutation
• output: object — --format plain prints its grid-scope reference (scope)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Examples:

lettuce grid scope add-dim s1 t s --project lettuce --author agent-1 --format json

Notes:

• Marker declarations under projects/<p>/grid/scopes/<scope>/dims/<member>; a scope that declares units but no applicable dims (or vice-versa) has grid size 0 and never reads a vacuous ratio. A malformed slug is refused before any write. REST parity: declared over HTTP via POST /v1/projects/<p>/grid/scopes/<scope>/dims (differential parity guarded).

grid scope remove-unit

Usage: lettuce grid scope remove-unit SCOPE UNIT... --project PROJECT

UNDECLARE unit (row) members from a scope's grid — the inverse of add-unit (LET-1473). It matters because the declared grid IS the coverage denominator: before this verb a single mistyped member slug permanently inflated |units|×|dims| on every surface (cell rollup, board export/next, the DoD gate) with no supported repair, so a scope with 100% of its real work done read 4/6 = 66.7% forever. REFUSES with FW-CMD-USAGE when a member still holds stored cells in that scope, naming the COUNT ("recovry holds 2 cell(s)") — they would be orphaned, so reassign or clear them first. Excluded (N/A) cells block removal too, and are named apart ("recovry holds 2 cell(s), all 2 excluded (N/A)") with the unwind recipe: clear the member's cells (cell clear per coordinate, listed by query run; cell clear-where on a local store), then remove it — the hardened ratio DIPS between the two steps (the cleared coordinates read untested inside the grid) and recovers once the member is gone (LET-1599). A member with NO stored cell removes without a refusal, and that shrinks the denominator with no work done, so the ratio RISES (LET-1601: reported, not blocked — grid scope show lists such members as unworked_units/unworked_dims). Idempotent: removing an undeclared member is a no-op, mirroring add.

• kind: mutation
• output: object — --format plain prints its grid-scope reference (scope)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Examples:

lettuce grid scope remove-unit s1 recovry --project lettuce --author agent-1 --format json

Notes:

• Removes the marker directory under projects/<p>/grid/scopes/<scope>/units/<member>; the denominator shrinks immediately and every ratio that consumed it is corrected. The refuse-when-in-use choice is NOT invented here — it mirrors defaults state hide, which already refuses a state still holding cells and reports the count, so the product carries one answer rather than two. The guard is scoped to the member's OWN scope: an identically-named member under a different scope is a different grid row and never blocks. Event-first ordering, so a crash mid-batch heals forward. REST parity: DELETE /v1/projects/<p>/grid/scopes/<scope>/units with the member list in the body — the same route and body shape the POST uses (differential parity guarded).

grid scope remove-dim

Usage: lettuce grid scope remove-dim SCOPE DIM... --project PROJECT

UNDECLARE applicable dimension (col) members from a scope's grid — the inverse of add-dim (LET-1473). Same refusal (excluded cells named apart with the unwind recipe, LET-1599), same idempotence, same arithmetic consequence as remove-unit: the declared grid is the denominator, so an un-removable mistyped dim capped every ratio for that scope permanently, and removing a never-worked dim raises the ratio with no work done (LET-1601; see unworked_dims in grid scope show).

• kind: mutation
• output: object — --format plain prints its grid-scope reference (scope)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• requires root: true
• requires project: true
• requires author: true
• stable snapshot: false
• idempotency key: false

Examples:

lettuce grid scope remove-dim s1 tt --project lettuce --author agent-1 --format json

Notes:

• Marker removal under projects/<p>/grid/scopes/<scope>/dims/<member>. REFUSED (FW-CMD-USAGE, with the count) while stored cells still name that dim in this scope. Removing the last dim leaves grid size 0, which reads as no declared grid rather than a vacuous ratio — the same state the scope had before any dim was declared. REST parity: DELETE /v1/projects/<p>/grid/scopes/<scope>/dims (differential parity guarded).

grid scope show

Usage: lettuce grid scope show SCOPE --project PROJECT

Show ONE scope's declared grid — its unit (row) members, applicable dim (col) members, the resulting size (|units|×|dims|), and the declared members that hold NO stored cell in this scope (unworked_units / unworked_dims, LET-1601: exactly the members remove-unit/remove-dim removes without a refusal, each removal deflating the denominator). Read-only; a scope that was never declared is REFUSED (FW-PATH-NOT-FOUND) — a declared scope always carries at least one unit or dim, so a member-less scope is a miss, not an empty grid (LET-1514).

• kind: read
• output: object — --format plain prints its grid-scope reference (scope)
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: bounded — bounded by the objects it names, independent of the project's size
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Examples:

lettuce grid scope show s1 --project lettuce --format json

Notes:

• A pure read over projects/<p>/grid/scopes/<scope>; size is |units|×|dims| — the scope's contribution to the honest coverage denominator. REST parity: read over HTTP via GET /v1/projects/<p>/grid (one scope filtered client-side).
• On an ARCHIVED project this read is answered (the explicit reference is the explicit ask) and labelled ARCHIVED: an FW-READ-PROJECT-ARCHIVED-SHOWN warning (stderr in table/plain, warnings[] in json/yaml) and project_archived_at in the json/yaml data.

grid show

Usage: lettuce grid show --project PROJECT [--include-archived]

Show a project's WHOLE declared grid — every scope with its units, applicable dims, size and unworked_units/unworked_dims (declared members holding no stored cell in that scope, LET-1601), plus the project denominator (Σ per-scope |units|×|dims|). Read-only; a project that declares no grid reads declared=false with denominator 0 (the coverage denominator then falls back to the observed stored-cell count — backward-compatible).

• kind: read
• output: report — --format plain prints the table bytes
• exit codes: 0 success; any failure: 1-7 by diagnostic class (spec §24.11)
• read cost: listing — proportional to the collection it reads once (paging or the task projection bound it)
• requires root: true
• requires project: true
• requires author: false
• stable snapshot: true
• idempotency key: false

Flags:

• --include-archived - Read an ARCHIVED project on purpose: without this flag a read scoped to an archived project is refused (FW-READ-PROJECT-ARCHIVED); with it the read succeeds and is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning, and project_archived_at in the json/yaml data).

Examples:

lettuce grid show --project lettuce --format json

Notes:

• The denominator here is the same declared applicable space rollup/board/dod use once a grid is declared (cells-v0.16 §A2). No declared grid ⇒ the observed-cell denominator (pre-implicit-cells behaviour). REST parity: read over HTTP via GET /v1/projects/<p>/grid.
• On an ARCHIVED project this read is refused with FW-READ-PROJECT-ARCHIVED (exit 1) unless --include-archived is passed; with it the result is labelled ARCHIVED (an FW-READ-PROJECT-ARCHIVED-SHOWN warning and project_archived_at in the json/yaml data).