This is the full, authoritative reference for every configuration block
tianluo reads. It is written against src/tianluo/config.py — every key below
corresponds to a real dataclass field, and every default is the value of the
corresponding DEFAULT_* constant (or the dataclass default) in that module.
tianluo.example.yaml is a getting-started sample, not a schema: it shows a
small, opinionated subset and it also carries a few historical blocks the engine
no longer reads. When the two disagree, this document (and the code it mirrors)
wins.
- Configuration files and resolution rules
- Blocks
- Legacy / historical configuration
- Troubleshooting: "I changed the config and nothing happened"
Project configuration lives in a single YAML file at the project root. Exactly
one file is selected — get_project_config_path() probes candidates in
order and stops at the first one that is a regular file:
| # | Candidate | Notes |
|---|---|---|
| 1 | <worktree>/tianluo.local.yaml |
Highest priority. Gitignored local override. |
| 2 | <main_repo>/tianluo.local.yaml |
Only probed when the project root is a linked git worktree. |
| 3 | <worktree>/tianluo.yaml |
The committed project config. |
| 4 | <main_repo>/tianluo.yaml |
Lowest priority. |
Tiers 2 and 4 exist only for git worktrees. luo run --worktree executes in
a linked worktree, and a gitignored tianluo.local.yaml does not travel there —
so the main repository's local override is consulted before the worktree's
committed tianluo.yaml. For a plain (non-worktree) checkout the lookup
collapses to the classic two tiers: tianluo.local.yaml > tianluo.yaml.
If none exists, <project_root>/tianluo.yaml is returned as the notional
target, and every loader falls back to built-in defaults.
Two details worth knowing:
- The probe uses
is_file(), which follows symlinks. A layout such astianluo.local.yaml -> ../shared-overrides.yamlis picked up as the active override (intentional — it is how users share overrides between clones). A stray directory or dangling symlink at that path is not a regular file and therefore does not shadowtianluo.yaml. - Relative paths inside the selected config (e.g.
version.version_file,test.command,test.phases[].cwd) are resolved by downstream callers against the project root of the running process, not against the directory containing the config file. A relative path written into a main-repotianluo.local.yamlis interpreted relative to the worktree that reads it.
The local override is whole-file select-one, not per-key merge. Once
tianluo.local.yaml exists, tianluo.yaml is never opened. Anything defined
only in tianluo.yaml silently reverts to its built-in default.
# tianluo.yaml (committed)
workflow:
max_fix_iterations: 100
agents:
primary: { type: claude-code, cmd: claude }
llm_caller:
defaults: [primary]# tianluo.local.yaml — "I just want to tweak one knob"
workflow:
self_check_passes_required: 2Result: max_fix_iterations falls back to the default 100 (coincidentally the
same here), and the project-level agents registry and llm_caller.defaults
are gone — the project side of those blocks is now empty. What the run
actually uses then depends on the global layer, in this order: the agents
entries and llm_caller.defaults declared in ~/.se3/config.yaml, then a chain
implied by a legacy claude_commands: block, and only if none of those supply a
chain does it reach the built-in PATH-probed one. So on a machine whose
~/.se3/config.yaml configures agents, the run silently switches from the
project's chain to the global chain — not to the built-in probe. To keep a
value, repeat it in the local file. This is why tianluo.example.yaml
annotates workflow.max_fix_iterations with "intentionally identical to
tianluo.local.yaml so the local override does not silently shadow a different
value".
Rule of thumb: tianluo.local.yaml is a full replacement config, not a
patch. Start it as a copy of tianluo.yaml and edit from there.
A related failure mode: a tianluo.local.yaml that is unparsable (YAML syntax
error, or a top level that is not a mapping) is treated as empty — it still
shadows tianluo.yaml, and every loader falls back to built-in defaults. The
loader emits a one-shot warning naming the offending file when this happens; if
your project config "stopped working", check the log for it.
A per-user global config is read from ~/.se3/config.yaml. The path comes from
_GLOBAL_CONFIG_PATH_SUFFIX = (".se3", "config.yaml") and did not change
with the se3 → tianluo rename — the directory is still ~/.se3/, alongside
~/.se3/server.db, ~/.se3/daemon.pid, and the rest of the per-user runtime
state. It is a normal YAML mapping using the same block names as the project
file.
Only some blocks participate in a project↔global merge. The rest are read from the project file only:
| Block | Global layer? | Merge granularity |
|---|---|---|
agents |
Yes | Entry-level. Project entries override global entries with the same name; non-conflicting entries from both sides coexist. |
llm_caller.defaults |
Yes | Whole-list. Project defaults wholly replaces global defaults; global is used only when the project omits the key. |
llm_caller.steps.<step> |
Yes | Per-step whole-value. A step declared in the project replaces the global declaration for that step; steps declared only globally still apply. |
confirmation.steps |
Yes | Entry-level, same rule as agents. |
language |
Yes | Field-level. Each of language / spec_language independently takes the project value when set, otherwise the global one. |
server |
Yes | Whole-block. A project server: section wholly replaces the global one (no deep merge). |
| everything else | No | Project file only (workflow, test, implement, steps, version, documentation, code_index, merge, conflict_resolver, claude_subprocess, investigation, presets, pricing, …). |
The pre-rename filenames are still honoured at every tier of the lookup, with
the canonical tianluo.* name always winning over the se3.* one at the same
tier. The effective order is therefore:
worktree/tianluo.local.yaml → worktree/se3.local.yaml
→ main/tianluo.local.yaml → main/se3.local.yaml
→ worktree/tianluo.yaml → worktree/se3.yaml
→ main/tianluo.yaml → main/se3.yaml
The se3.* fallback keeps working through 12.x and is removed in 13.0.0.
The ancient se3.config.yaml is recognised only as a project-root marker (for
the CLI's parent-directory walk), never loaded as config.
- Default columns quote the literal value the code uses. Where the code
names a constant, the constant is the source of truth
(
DEFAULT_MAX_FIX_ITERATIONS = 100,DEFAULT_CODE_INDEX_CHUNK_BYTES = 16 * 1024, …); the numbers here are those constants' current values. - Type is the YAML type accepted, not the Python annotation.
- Unless a key's entry says otherwise, loading is clamp-and-warn: an illegal
value logs a warning and falls back to the default rather than aborting the
run. The exceptions that fail fast are called out explicitly
(
ConfigError/ValueError), because they abort the flow at load time. - A key documented as inert is parsed by
config.pybut has no consumer in the engine. It is listed for completeness (so you do not go hunting for a behaviour it never had), not as something worth setting.
The top-level identity layer. Every llm_caller.* entry and every
confirmation.steps.<step>.reviewer is a name reference resolved against this
registry. It is a mapping keyed by agent name.
agents:
primary: { type: claude-code, cmd: claude }
cheap: { type: claude-code, cmd: hclaude }
gpt: { type: codex, cmd: codex }
tty: { type: claude-interactive, cmd: claude }Each entry corresponds to an AgentDef:
| Key | Type | Default | Meaning |
|---|---|---|---|
| (map key) | string | — | The agent's name. Must be a non-empty string; other keys are skipped with a warning. |
type |
string | claude-code |
Which AgentRunner adapter drives this agent. See the table below. |
cmd |
string | — | The CLI command to invoke. Required — an entry with no usable cmd is skipped with a warning. |
provider |
string | "" |
Declared LLM provider for this agent (e.g. anthropic, openai). Used as the declared fallback for usage accounting when the runner's stream reports no provider; it never overrides a provider-reported value. |
model |
string | "" |
Declared model for this agent. After environment-variable expansion it feeds the canonical resolved_model fallback chain (provider report → expanded agent model → runner startup metadata → unknown); a literal like $ANTHROPIC_MODEL never enters resolved_model — the raw value stays in reported_model for diagnosis. |
priority |
int | 0 |
Deprecated and ignored. Rotation order is the written order of the name lists in llm_caller, not this number. Setting it emits a one-shot deprecation warning per source. |
A shorthand form is accepted: primary: claude is equivalent to
primary: { type: claude-code, cmd: claude, priority: 0 }.
Valid type values (dispatched in LLMCaller; an unrecognised type raises
ValueError: Unknown agent type: … at the first call, not at config load):
type |
Adapter | Notes |
|---|---|---|
claude-code |
claude_runner.ClaudeRunner |
One-shot claude -p subprocess. The default. |
codex |
codex_runner |
OpenAI Codex CLI. |
claude-interactive |
claude_interactive_runner |
pexpect-driven interactive PTY session. Opt-in only — it needs a terminal and pexpect, so it is never auto-selected. |
Unknown names fail fast. Referencing an agent that is not in the merged
registry raises a ValueError at config-load time (listing the registered
names), so a typo in llm_caller.defaults or a reviewer name aborts the run
before any LLM call is made.
Project + global merge is entry-level: ~/.se3/config.yaml can hold your
machine-wide agent inventory and a project only needs to add or override the
entries it cares about.
When agents is omitted entirely the default chain is probed from PATH,
in this order: claude (type claude-code), then codex (type codex). All
available candidates form the chain; if none is on PATH, loading raises
ValueError. claude-interactive is deliberately excluded from this
auto-probe.
The removed list form (agents: [ … ]) and the legacy claude_commands: key
are still detected: the list form is warned about and ignored wholesale;
claude_commands is auto-migrated into a synthesized registry plus an implicit
llm_caller.defaults (with a one-shot warning that prints the equivalent
new-schema YAML). Setting both agents and claude_commands in the same source
ignores claude_commands.
Which agent chain runs which step.
llm_caller:
defaults: [primary, cheap]
resume_strategy: native
steps:
implement: [primary]
self_check: [[primary], [gpt]]| Key | Type | Default | Meaning |
|---|---|---|---|
defaults |
list of agent names | built-in PATH probe | The default rotation chain for any step without an override. Written order is rotation order. |
resume_strategy |
native | rebuild |
native |
How a continuation reaches the agent. native continues the recorded provider session in place; rebuild always reconstructs the conversation into a new prompt. An unrecognised value warns and falls back to native. |
steps |
mapping <step> → list of agent names |
{} |
Per-step hard overrides. Keys must be StepType values; unknown keys log a one-shot "likely a typo" warning and are ignored. |
Rotation semantics: within a chain, the LLMCaller rotates to the next agent on
infrastructure errors. Rotation happens strictly inside the selected list —
a single runner never rotates on its own, and a step override never spills over
into defaults.
Every continuation (after an interjection dialog, after a failure you chose to
retry, on luo run --resume, on a JSON retry, and on the engine's own internal
retries) first tries to continue the agent's existing provider session:
claude -p --resume <session_id> for the Claude adapters,
codex exec resume <thread_id> for codex. The working directory a call was
opened in is always written to the step's history before the subprocess
starts (a resume must be launched from the same cwd), but when the session id
itself lands depends on the provider:
| Adapter | Session identity | Recorded |
|---|---|---|
claude-code, claude-interactive |
pre-allocated by tianluo and passed in as --session-id <uuid> |
with the prompt, before the subprocess starts |
codex |
minted by the CLI, first seen in its thread.started event |
the instant that event streams — the prompt record is written with an empty id and back-filled to the real one within the same attempt |
So a Claude attempt always leaves an addressable session, even one killed
before it produced a single line. A codex attempt is addressable only from
thread.started onwards: interrupt it earlier (or have it fail to start at
all) and there is no thread id to resume, so the next continuation takes the
rebuilt-context path below. That is the expected behaviour, not a lost session.
Either way the invariant holds that both records of one attempt name the same session, and never a previous attempt's.
Native resume is used only when the recorded session's agent is still in the configured chain (matched by name and runner type) and that runner declares the capability. Otherwise — and whenever a resume fails for any reason (a pruned session, an unsupported flag, a transcript the provider will not continue) — the engine falls back to the rebuilt-context path without failing the call, and a rotation to a different agent always rebuilds. Every attempt records which strategy it used.
A two-phase step's Phase-2 JSON extraction is deliberately invisible to this selection. It opens its own provider session whose whole content is "re-express this text as JSON", so a continuation resumes the Phase-1 working session behind it (or rebuilds) rather than the re-formatter.
Set rebuild to take the provider's own session state out of the picture while
troubleshooting; it costs more input tokens per continuation but is otherwise
behaviour-preserving.
Declaring a step here replaces the chain for that step. There is no implicit
append of, or fallback to, defaults. If you want the default agents as a tail,
you must list them.
llm_caller:
defaults: [primary, cheap, backup]
steps:
# WRONG if you meant "try opus first, then the usual chain".
# implement now has exactly ONE agent; on infra failure there is
# nothing to rotate to.
implement: [opus]
# RIGHT — the default tail is spelled out.
plan: [opus, primary, cheap, backup]Precedence between sources is also whole-value: if a step is declared in the
project config, the global ~/.se3/config.yaml declaration for that same step is
ignored entirely (no concatenation, no dedup).
Degenerate declarations are treated as no override (warn, then fall back to
defaults): a non-list value, an empty list, a list whose entries are all
invalid, and the removed inline-dict form (- cmd: claude-opus). Only an
unknown agent name is fatal.
llm_caller.steps.self_check additionally accepts a list of lists — one
chain per self_check pass:
llm_caller:
steps:
self_check:
- [primary] # pass 1
- [gpt] # pass 2 — a different vendor reviews the same diff
- [primary, cheap] # pass 3- Flat form (
self_check: [a, b]) — one chain reused for every pass. Fully back-compatible. - Nested form — chain i drives pass i (1-based). Passes beyond the number of declared chains reuse the last chain.
- Mixed form (bare names and sub-lists in the same list) is a config error:
it warns and falls back to
llm_caller.defaults.
The nested form also determines the pass count. When
workflow.self_check_passes_required is not set explicitly, the effective
number of passes is the number of declared chains — the chain list alone
expresses the intent. When both are set, the explicit count wins (and
over/under-shooting reuses or skips chains as described above).
Which steps are gated by a review before the flow moves on.
confirmation:
steps:
plan:
max_iterations: 3
adjudicate:
reviewer: human| Key | Type | Default | Meaning |
|---|---|---|---|
steps |
mapping <step> → entry |
{} |
A step is confirmed iff it appears as a key here. No step is exempt from this rule. |
steps.<step>.reviewer |
string or null | null |
human → routes to the tianluo/calls/ MCP call file + interactive approval. An agent name → single-agent LLM review with that agent. Omitted/null → LLM review via llm_caller.defaults. |
steps.<step>.max_iterations |
positive int | 3 (_CONFIRM_DEFAULT_MAX_ITERATIONS) |
Cap on the review→modify→re-review cycle. Non-integer or <= 0 warns and falls back to the default. |
There is no global on/off switch. Only the keys present in
confirmation.steps are confirmed. Unknown fields inside a step entry (anything
other than reviewer / max_iterations) are warned about once and ignored.
An unknown reviewer agent name raises ValueError at load time — and the check
walks every entry, not just the step about to run, so typos under a step that
happens not to be in this flow's sequence still surface at startup.
plan-confirm is opt-in, like every other step. It used to be always-on —
a CONFIRM step was inserted after every plan step regardless of this block.
It no longer is: with no confirmation.steps.plan entry, PLAN is followed by
no gate at all. The reason for the downgrade is that self_check is already
task-description-authoritative and verifies requirement→code coverage against
the real code, while under the default coarse-grained
capability doctrine a
requirement→task coverage review has lost its discriminating power — a group
that says "implement the export capability" cannot be checked line-by-line
against a requirement list.
To keep a gate, declare it like any other step:
confirmation:
steps:
plan:
reviewer: human # manual grouping gateWhat the review asks depends on the doctrine the flow was planned under:
capability— reviews the grouping: whether the group count equals the number of independent tasks (and whether every further split names a capability-edge reason that holds), whether any group was cut along a forbidden artifact type or code layer, and whether thedepends_ondeclarations hold. It explicitly does not ask for a per-requirement task decomposition.granular— keeps the legacy requirement→task coverage review verbatim.
The doctrine is read from the persisted flow context, so a resumed flow is
reviewed under the doctrine it was planned with. The granularity travels with
it, because it pins the group count: under single the count is a configured
guarantee PLAN may not deviate from, so the review puts it out of scope
entirely; under conservative the deliberate over-splitting that setting orders
is not a defect. Only under auto is the count PLAN's own judgement, and only
there may the gate ask for it to be regrouped — otherwise the reviewer would
demand a revision PLAN is forbidden to produce, and the loop would just spin to
max_iterations.
By contrast adjudicate is unconfirmed by default: with no entry here a
ruling auto-passes with no gate — including a ruling that rewrites the task
description. If an unattended run must not silently rewrite its own task, opt
in with adjudicate: { reviewer: human }.
Deprecated keys, detected and ignored with a one-shot warning per source:
confirmation.enabled, top-level confirmation.reviewer,
confirmation.llm_reviewer, and the list form of confirmation.steps.
Two independent language settings, merged field by field with
~/.se3/config.yaml.
| Key | Type | Default | Meaning |
|---|---|---|---|
language |
string or null | null |
The unified human language. Drives both the CLI/console UI copy (via the i18n catalogs) and the language injected into human-facing LLM step outputs (summarize / discovery / confirmed steps). e.g. zh-CN, en-US. null = no restriction on LLM output (UI copy still resolves through the chain below). |
spec_language |
string or null | null |
The knowledge-asset language — the writing language of tianluo/charter.md and the code-index, injected into the charter_freshness and code-index summary prompts. null = no restriction. |
CLI UI-text resolution order: SE3_LANG env > this key (project, then
global) > system locale (LC_ALL / LC_MESSAGES / LANG) > en-US. en-US
is the baseline catalog holding the full key set; a missing key or unsupported
language code falls back to it.
Changing either setting affects only content generated after the change; it does not retroactively translate existing knowledge assets.
The central WebUI console's interface language is a per-user browser / localStorage preference and does not follow this project setting.
Fix-loop and self_check behaviour. Loaded into WorkflowConfig.
| Key | Type | Default | Meaning |
|---|---|---|---|
max_fix_iterations |
int >= 0 |
100 |
Cap on the test→verify→fix loop. 0 (or null) means unlimited. Negative → ConfigError. A float (even 0.0) or bool warns and falls back to 100 — the unlimited sentinel must be the literal int 0 or null. |
self_check_passes_required |
int >= 1 |
1 |
How many self_check passes must run. < 1 → ConfigError. bool/float/non-integer warns and falls back to 1. See the nested-chain interaction in llm_caller. |
baseline_fix_max_attempts |
int >= 0 |
3 |
Per-flow cap on looping inherited (pre-implement baseline) test failures. Deliberately independent of max_fix_iterations, which may be the unlimited sentinel — inherited failures must stay bounded on their own. 0 disables baseline looping entirely (inherited failures are surfaced, never looped). Negative → ConfigError. |
self_check_defer_fix_threshold |
int >= 0 |
0 |
For nested self_check chains: when a non-final pass finds fewer than this many issues and none is critical/high severity, its fix is deferred so the remaining passes run first; their findings are then deduped into one consolidated fix loop. 0 (or null) disables deferral — every issue-finding pass fixes immediately (the historical behaviour). Negative → ConfigError. |
adjudicate_period |
int >= 0 |
10 |
Period, in fix iterations, of the adjudicate step's catch-all safety net: every N fix iterations one adjudicate run is forced even when no structural oscillation signal fired. 0 (or null) disables the periodic net (adjudicate then runs only on the structural triggers: candidate oscillation / contradiction / recurrence). Unlike its siblings this key is fail-fast on a bad type: a bool, a float, or a non-numeric string raises ConfigError rather than defaulting, because silently defaulting would enable an interval the user never asked for. A cleanly integer-valued string ("7") still coerces. Negative → ConfigError. |
plan_decomposition |
capability | granular |
capability |
Which decomposition doctrine PLAN follows (see below). Fail-fast on any other value — a typo would otherwise silently pick a different doctrine, invisible until the groups come out the wrong size. |
plan_granularity |
auto | single | conservative |
auto |
Group-count pressure applied under capability only; meaningless and ignored under granular. auto = group count equals the number of independent tasks, more groups only at the capability edge; single = pin exactly one group; conservative = lower the splitting threshold, err toward more groups. Fail-fast on any other value. |
The retired workflow.self_check_convergence_enabled key is accepted only for
configuration compatibility. It is always normalized to false, and the
deprecation warning is emitted once per process (a long-lived daemon /
server that reloads the config repeatedly logs it only on the first load);
validated findings always enter the fix loop.
There is one path, not two. feature, bugfix and discovery flows always
run ANALYZE → PLAN → IMPLEMENT; no configuration key removes PLAN from a
sequence any more. What varies is what PLAN emits and how many groups it
emits — and, wherever the granularity left the group count to PLAN, the
execution shape of the PLAN → IMPLEMENT segment is read off that count, not
off a routing flag:
- one group → IMPLEMENT runs the whole task as a single autonomous
implement call (what the retired
directpath used to select explicitly); - two or more groups → the existing DAG scheduling applies: groups with no dependency between them run in parallel in isolated worktrees and are merged back, groups with declared dependencies run in order.
The one exception is plan_granularity: single (described below), which pins
the one-call shape as a configured guarantee: however many groups PLAN emits,
the whole task is delivered by a single autonomous call.
Task type and decomposition remain different layers: the task type
(feature / bugfix / small / review / survey / discovery) decides the
whole flow's step composition and quality gates, while these two keys only
shape the PLAN → IMPLEMENT segment. Sequences that never had a PLAN step
(small, review, survey) are unaffected.
plan_decomposition: capability (default) — PLAN cuts the work into coarse
groups whose unit is the task: one coherent piece of work the user would
regard as a single thing. The only reason to split a task any further is
"can a single autonomous implement call safely carry this?":
- one task that one call can complete → one group (the group's content is simply "carry out that task");
- one task one call cannot carry → two or more groups;
- two or more mutually unrelated, independent tasks → one group each, so they can be executed in parallel in isolated worktrees. Aspects of one coherent task are not independent tasks and stay together in its group;
- default to aggregation — one task, one group. Split a task only at the capability edge: PLAN positively judges that a single autonomous implement call cannot complete it, or that forcing it into one call would substantially degrade the quality of the execution — and records that reason in the group's description. PLAN never pre-cuts a single task along implementation phases, implementation paths, or artifact types: how a task breaks down internally is decided inside the implement call, not by PLAN.
A hard guardrail forbids cutting groups along artifact types or code layers: no separate test group, docs group or config group, and no group defined by a file set, module boundary or layer. Testing and verification are part of what each group itself delivers. (A group whose task happens to concern the test or docs system — "fix the flaky retry in the test runner" — is of course legitimate; what is forbidden is carving one task's tests out into a group of their own.)
Under capability, PLAN emits no per-task listing. A group carries only
the scheduling fields group_id / name / description / group_order /
depends_on; the in-group breakdown is left to the implement runner's own
planning / sub-agent system, which decomposes against the real code at
execution time. Both runners support headless subagents — claude -p exposes
the Agent (subagent) tool, and codex ships subagents enabled by default under
non-interactive codex exec — but codex only spawns them when explicitly
instructed, so the implement prompts state that permission explicitly. PLAN
produces no proposal and no design document either: its whole output is the
scheduling data (the groups plus total_complexity / estimated_effort), and
that is what a human gate reviews. Project conventions reach the implement call
through the charter and the code-index instead.
plan_granularity applies only under capability:
auto(default) — the group count is the number of mutually independent tasks in the requirement, normally one group per task. Groups beyond that count are added only where a single task reaches the capability edge and genuinely needs more than one autonomous implement call.single— exactly one group, whatever the task's size. This is the configuration-forced equivalent of the retireddirectpath, and it is a guarantee rather than a request: PLAN is instructed to emit one group, but if it emits several anyway, IMPLEMENT still runs the whole task through the one autonomous call and passes the groups in only as an outline. Undersinglea flow therefore never fans out into a parallel worktree DAG.conservative— lower the splitting threshold: whenever there is any doubt that one call can carry a task, split it. Prefers one group per sub-task even where the default sizing would have kept the task whole, and errs toward more groups, on the reasoning that an under-sized group costs little while a group that overflows the call it was sized for costs a failed implementation.
plan_decomposition: granular is the retained legacy doctrine: the
fine-grained per-task listing (tasks arrays with complexity /
estimated_loc / files), the LOC-driven merge and DAG thresholds, and the
requirement→task coverage review at the plan gate — all unchanged from before
this model existed. plan_granularity is ignored in this mode.
Priority for a new flow: explicit CLI (--plan-decomposition /
--plan-granularity) / web request → the two config keys → capability +
auto. The decision is made once, at flow creation, and persisted in the
flow context together with its reason; a resumed flow keeps executing the
doctrine it already entered, whatever the configuration says later, and the
groups PLAN already emitted are never re-judged mid-flow. Flows created before
this model existed carry no new keys: they are described read-only by the
retired strategy value they recorded, and their on-disk state is never
rewritten.
The implementation_strategy routing axis (auto / direct / planned) is
retired. Both workflow.implementation_strategy and the
--implementation-strategy CLI option are still accepted for one version
and mapped onto the new keys, with a deprecation warning emitted once per
process. They will be removed in the next major version.
| Legacy value | Maps to | Because it meant |
|---|---|---|
direct |
plan_granularity: single |
"do the whole thing in one call" = force a single group |
planned |
plan_decomposition: granular |
"I want fine-grained task groups + DAG scheduling" = keep the legacy doctrine |
auto |
the new defaults (capability + auto) |
"let the flow decide" |
The mapping happens at the config-object boundary (and, for the CLI, through the same table), so nothing downstream carries two dialects. A new key you actually wrote always wins: the legacy key is a fallback for un-migrated projects, never an override. An out-of-range legacy value is still fail-fast.
SELF_CHECK is judged against the effective task description (the original
task or the discovery refined description, user interjections, and the
adjudicated description) plus the charter and WHY:/INVARIANT: project
constraints. PLAN, task_groups, the implementation summary and the legacy
adjudicated_plan are scheduling / history hints only — they can never
narrow, widen or override the requirements.
Rounds are scoped by a persisted, recoverable baseline (stored in runtime state, never in git; the workspace diff is rebuilt from it).
Both round modes are diff-scoped. full and incremental are the
persisted scope_mode values, and they name the diff baseline — not the
presence or absence of a diff. A full round is not an unscoped read of the
whole tree: it reviews the diff from this flow's implementation baseline
(everything the flow changed). An incremental round reviews the diff from the
fix baseline that round was scoped with — the earliest fix the flow has not
reviewed yet, so its delta spans every fix captured since, which may be more
than one. Every round prompt carries a
scope manifest — the changed paths, their +/- counts and the exact line
ranges a citation may reference — and the full diff text, either inlined or
pulled on demand with the read-only luo review-scope diff command. Rebuilding
the range by hand with git diff is wrong and the prompt forbids it: a
baseline is a workspace content snapshot, not a commit, and HEAD advances
inside a flow.
- Before the first IMPLEMENT, an implementation baseline is captured so
the first review covers everything this flow changed and excludes the
user's pre-flow working-tree modifications. Commits the flow makes itself
(for example the per-group merges of a planned multi-group IMPLEMENT) stay
inside the scope — the baseline is content-keyed, so it survives HEAD
moving forward; only history that no longer contains the baseline commit
(rebase, amend, a backwards reset) is undecidable. The first SELF_CHECK
round is
full— the complete requirements against the diff from that implementation baseline. A clean full round proceeds directly to the next gate. - Before every FIX, a fix baseline is captured; the post-fix round is
incremental— diff-scoped from the earliest fix baseline no round has reviewed yet, so when several FIX calls run back to back the delta covers all of them rather than only the last. Attention is focused on that exact diff, its changed files and the still-open findings. Checkers may still read the whole repository, the charter, the code-index, test results and unmodified code, and must trace impact along call chains, shared state, protocols, data formats, configuration, concurrency and invariants: the scope controls attention, never tool permissions. - A clean incremental round is followed by a full closure round; only a clean closure round reaches INVARIANT_CHECK. A closure finding re-enters FIX and the incremental → closure cycle repeats.
- Any change to the effective task description (adjudication, interjection) or an undecidable baseline forces a full round — i.e. the round falls back to the implementation baseline; an empty diff is never used to fake an incremental review.
- TEST always runs the project's full configured test commands — SELF_CHECK scope never selects or shrinks tests.
All validated findings — deferred, repeated, or adjudicated — always enter the fix loop; there is no convergence / severity / divergence path that passes a round with unresolved findings.
Each SELF_CHECK step persists its scope_mode, baseline id, changed paths, fix
iteration and pass index for the CLI history view and the web console's scope
audit. Both surfaces render the mode as full diff / incremental diff and
state which baseline it diffs from, so the persisted value is never read as
"non-diff review"; the persisted values themselves stay full / incremental.
WorkflowConfig also carries a field named self_check_passes_required_explicit.
It is not a config key — it is derived at load time (it records whether
self_check_passes_required appeared in the YAML) and feeds the nested-chain
pass-count resolution. Writing it in YAML has no effect.
Note the shared sentinel convention across this project: for every iteration
cap, 0 and null mean "unlimited / disabled" and a negative value is a
fail-fast error. That rule holds for workflow.max_fix_iterations,
workflow.self_check_defer_fix_threshold, workflow.adjudicate_period and
investigation.max_iterations alike.
At load time the resolved max_fix_iterations and its winning source file are
logged once per config path (workflow config: max_fix_iterations=… (effective source: …)), specifically so a tianluo.local.yaml shadowing the committed
value is visible rather than mysterious.
Model pricing overrides for the session usage/cost summary. Loaded into
PricingConfig and merged onto the built-in versioned price table (every
built-in entry records its catalog version, source URL and effective date).
| Key | Type | Default | Meaning |
|---|---|---|---|
pricing.models.<canonical_model>.<category> |
number >= 0 |
built-in table | USD per million tokens for one price category of one model. Categories: input / uncached_input, output, cache_read, cache_creation / cache_write, cache_creation_5m, cache_creation_1h. |
Behavioural notes:
- Model keys are alias-normalized before merging (
Opus-5→claude-opus-5). A key that maps to neither an alias nor a built-in entry defines a new entry for that exact name. - A non-numeric, boolean, or negative value drops the offending model entry (with a warning) while valid sibling overrides still apply; pricing is display accounting, so a typo must not fail the flow but must also never silently become a wrong price.
- Provider-reported actual cost is always authoritative. Estimates cover only
calls that reported tokens but no actual cost, and only when the model and
every nonzero token category have a price — unknown model, unknown price,
or a missing cache-TTL price renders as "unknown cost", never as
$0. - Uncatalogued providers (e.g. Codex, which bills by subscription) simply show tokens with unknown cost.
Every LLM call/attempt is recorded as a unified usage record (usage_status,
agent, runner, provider, provider session, reported / resolved model, token
categories, provider actual cost). The record is the single accounting unit;
the flow session summary, luo history show, the daemon history payload and
the web console all render the same backend aggregation — the frontend
never re-sums provider sessions, cached tokens or pricing itself.
- Provider-reported actual cost is de-duplicated by billing session / call semantics and stays the authoritative actual column. Estimated cost covers only billing units that reported tokens but no actual cost, using the merged price table. Actual and estimated are always shown as separate columns — never added into a fabricated "total".
- Missing usage, missing model, missing price, or an unknown cache TTL is
displayed as unknown / partial, never as a misleading
$0. Explicit zero-usage reports stay distinguishable from missing data, and legacy five-field records are flaggedlegacyrather than guessed at. luo history show <flow_id>prints the per-call, per-step and flow totals (with--jsonemitting the same structured payload), and the web console's history view and live-flow sidebar show the same figures plus the plan mode (decomposition / granularity / group count) and the self-check scope audit. Active, archived and history-only flows are all recoverable; flows predating the unified records are marked incomplete instead of being rewritten.
The investigate step's own bounded loop. investigate handles
"symptom known, cause unknown" work: it may add temporary logging or
verification patches, but must restore everything before the step ends (net-zero
diff, snapshot-verified by the engine).
| Key | Type | Default | Meaning |
|---|---|---|---|
max_iterations |
int >= 0 |
3 |
How many investigation rounds may run when a round ends inconclusive (conclusive=false). 0 (or null) = unlimited. Negative → ConfigError. bool/float warns and falls back to 3. |
Exhausting the budget does not fail the flow: it proceeds to plan carrying
the best hypothesis so far, flagged low-confidence.
This loop is deliberately separate from the fix loop
(workflow.max_fix_iterations): an investigation round is an exploration
budget, not a repair attempt, and sharing one counter would let a long repair
history starve investigation (or the reverse).
The test step's command, timeouts, extra phases, and the skip-is-not-a-pass
gate. Loaded into TestConfig. All eight fields:
| Key | Type | Default | Meaning |
|---|---|---|---|
command |
string or null | null |
The primary test command, split with shlex. null → auto-detect from the project layout: pytest.ini or pyproject.toml → <python> -m pytest -v; package.json → npm test; Cargo.toml → cargo test; go.mod → go test ./...; otherwise <python> -m pytest -v. |
timeout |
int (seconds) | 1800 |
Fallback timeout for the primary command, and the default timeout for any phase that does not set its own. Unlike its siblings this key is not individually clamp-and-warn — see the note below. |
phases |
list of maps | [] |
Additional commands run after the primary one. Entry schema below. |
timeout_multiplier |
float >= 1.0 |
2.0 |
Multiplier applied to the LLM's estimated test duration when computing the dynamic timeout. Clamped up to 1.0 with a warning, so a typo like 0 or 0.1 cannot silently disable the feature. Non-numeric warns and falls back to 2.0. |
min_dynamic_timeout |
int >= 1 (seconds) |
30 |
Floor for the computed dynamic timeout. Clamped up to 1 with a warning. |
max_dynamic_timeout |
int (seconds) | 14400 (4 h) |
Ceiling for the computed dynamic timeout, so repeated fix-loop timeouts cannot compound the estimate without bound and mask a hung test as "just slow". The effective default is max(14400, timeout) — a project that deliberately sets a larger test.timeout is not capped below its own explicit intent. If the configured value is below min_dynamic_timeout it is raised to match, with a warning. |
critical_tests |
list of strings | [] |
Acceptance tests that MUST genuinely run. See below. |
parallel |
"auto" or int >= 1 |
null |
Run the primary command under pytest-xdist. null (the default) = serial, exactly as before this key existed. Anything else — 0, a negative, a float, true, an unknown string — warns and falls back to serial. See below. |
Gotcha — a bad
timeoutdiscards the whole block.TestConfig.load()wraps its parsing in a blankettry/exceptthat falls back to an all-defaultsTestConfig. Most keys are validated individually and clamp and warn, buttimeoutis coerced with a bareint(...), so a value liketimeout: "30m"raises inside that block and silently discards yourcommand,phases, andcritical_testsalong with it. The only symptom is one log line:Failed to load TestConfig from …, using defaults: …. Write plain integer seconds.
phases[] entry keys (read directly by the test step):
| Key | Type | Default | Meaning |
|---|---|---|---|
name |
string | — | Phase label, used in results and logs. Required in practice. |
command |
string | — | The command, split with shlex. Required. |
cwd |
string or null | project root | Working directory, resolved against the project root. |
timeout |
int (seconds) | test.timeout |
Per-phase timeout. |
required |
bool | true |
When true, a failing phase makes the whole run fail. false = informational. |
in_fix_loop |
bool | true |
When false, the phase is skipped during fix iterations (get_phases_for_run(is_fix_iteration=True) filters on it) — useful for a slow smoke suite you only want on the first pass. |
Both the primary command and each required phase get one in-place retry on timeout before being treated as a failure, so a transient slowdown does not push the flow into the fix loop.
critical_tests — the "skip must not count as a pass" guard. pytest exits
0 for a SKIPPED test, and a test that has been renamed or silently
un-collected (import error, typo'd pattern) simply vanishes from the output
while the run still exits 0. Either case would otherwise let tests_passed
(and downstream verified) go false-green. Each entry is matched as a
substring of pytest's per-test id (path/to/file.py::test_name), so a
fully-qualified id is the precise anchor and a bare file path matches every test
in it. For each pattern:
- matches one or more skipped tests → those ids are reported as
critical_skippedand the run is not verified; - else matches one or more tests that actually ran (passed or failed) → the pattern is considered genuinely exercised (a real failure is surfaced through the normal failure path);
- else → reported as
critical_missingand the run is not verified — but only when the run produced parseable per-test results at all.
That last caveat matters: under a non-verbose test command nothing is parseable,
so missing-detection is skipped (with a warning) to avoid flagging every pattern
as missing. critical_tests requires a verbose per-test-output command such
as python -m pytest -v.
The list is empty by default — this is an explicit opt-in, so ordinary platform / optional-dependency skips are never penalised. A non-list value warns and disables the gate rather than raising.
parallel — opt-in pytest-xdist parallelism. auto gives one worker per
CPU, an integer pins the worker count. The value is appended to the primary
command as -n auto / -n N, together with --dist loadgroup:
test:
parallel: auto # -> <primary command> -n auto --dist loadgroupThree boundaries are worth knowing:
--dist loadgrouprides along. It is the only scheduling mode under which pytest'sxdist_groupmarker means anything — tests sharing a group name run on the same worker, and therefore sequentially. That is how a suite keeps its genuinely order-dependent tests (a shared git worktree, shared mutable global state) from colliding, so the switch would be unsafe without it. If your command already specifies a--distmode, your choice wins and thexdist_groupserial-group guarantee is lost with it. The same applies to-n/--numprocesses: an explicit worker count in the command is never overridden.- Primary command only.
phases[]entries are commands you wrote, and they are executed verbatim — this switch never rewrites them. A non-pytest primary command (npm test,cargo test, …) is likewise left alone, with a debug log line saying so. - A missing plugin is an error, not a silent fallback. If pytest-xdist is
not installed in the environment that runs the tests, the step ends as
FAILEDwith an install instruction and goes to you — it never degrades to a serial run (which would report success for something you did not get) and never enters the fix loop (no code change can install a package). For a<python> -m pytest …command this is detected before anything runs, by probing that same interpreter; for a barepytestcommand — whose interpreter cannot be known up front — it is recognised from pytest'sunrecognized arguments: -n …output afterwards.
Parallelism is only safe for a suite whose tests do not depend on execution order or share mutable global state, which is why it is opt-in.
End-to-end testing: build a real, isolated environment (one container network,
one or more services), drive the project inside it, and assert on what actually
happened. Loaded into E2EConfig. Off by default — with e2e.enabled false
or the block absent, the state machine never inserts the E2E step and the flow
behaves exactly as it did before the subsystem existed.
This block carries only runtime settings. The content of e2e — services,
build steps, scenarios, baseline images — lives in a separate
tianluo/e2e/ directory.
The split is deliberate: enabled is the user's promise (that a container
runtime is installed and that the fix loop may spend time on scenarios), and the
flow never flips it — at most it prints a suggestion that the project looks like
a good e2e candidate. Content, by contrast, is authored and evolved by the flow
just like test code. Because the two live in different files, "the flow never
writes tianluo.yaml" is checkable by looking at which paths were touched.
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled |
bool | false |
Master switch. When false the E2E step is never inserted into any step sequence. Accepts the usual boolean spellings; an unrecognised value warns and stays false. |
runtime |
auto | docker | podman |
auto |
Which container runtime to use. See Runtime selection. An invalid value warns and falls back to auto. |
oci_runtime |
string or null | null |
Passed through to the runtime's --runtime flag. Point it at a VM-grade OCI runtime (Kata Containers and friends) to get VM-boundary isolation by configuration alone, with no separate backend. null = the container runtime's own default. |
build_timeout |
int >= 1 (seconds) |
1800 |
Budget for building a service image. Separate from scenario_timeout because image builds are the slow half (dependency installs on a cold layer cache) and scenarios the fast half. |
scenario_timeout |
int >= 1 (seconds) |
300 |
Default per-scenario budget. A scenario may override it with its own timeout:. |
estimated_e2e_duration |
int >= 1 (seconds) or null |
null |
The e2e counterpart of test.estimated_test_duration's role: lets a supervising runner tell "still running" apart from "hung". |
scenarios |
list of strings | [] |
Scenario selection by name. Empty means "run everything", not "run nothing". Narrow it so a fix loop need not replay the full suite on every iteration — the same precedent as test.critical_tests. |
critical_scenarios |
list of strings | [] |
Scenarios that must genuinely run for the result to count. Every name listed here is added to whatever the selection resolved to — narrowing scenarios for speed, or passing --scenario while debugging, cannot quietly drop one — and a critical scenario that produced no passing result makes the run fail, the same "a skip is not a pass" guard test.critical_tests applies. A name that no declared scenario answers to is a configuration error: the guarantee could never be met. |
keep_environment |
bool | false |
Leave containers and the network alive after the run so you can attach and look around. Debugging aid; the run prints the exact rm -f / network rm commands to clean up. |
Every field follows the clamp-and-warn policy used by test: a
malformed value is logged and replaced by its default rather than raising, so a
typo in one knob never makes the project unloadable.
e2e needs Docker or Podman, and you install it yourself — exactly as you
installed the claude / codex CLIs. pip cannot provide a container runtime.
tianluo and its e2e subsystem run entirely as your normal user. No code path
calls sudo or requires root. The prerequisite is therefore precisely: the
current user can run docker or podman without sudo. Any one of these
satisfies it:
- your user is a member of the
dockergroup; - rootless Docker (
dockerd-rootless-setuptool.sh installships with Docker); - Podman, which is rootless natively via user namespaces and works out of the box for an unprivileged user.
Under a rootless runtime the bind-mounted source tree is UID-mapped (Podman's
--userns=keep-id) so that files a container writes into your source directory
end up owned by you — never as root-owned residue you cannot clean up.
Check the host before enabling:
luo e2e doctorThe tier-2 (baseline screenshot diff) image comparison needs one third-party Python package, isolated behind an optional extra:
pip install 'tianluo[e2e]'The framework code and the Dockerfile templates ship with every install —
the extra isolates a dependency, not tianluo's own code. A core-only install
stays importable; a project that enables e2e without the extra and reaches a
tier-2 assertion gets an actionable "install tianluo[e2e]" message rather than
a ModuleNotFoundError.
auto probes by executing docker info, then podman info, and takes the
first that succeeds. This is deliberately not a PATH lookup: the most common
failure is a runtime that is installed but unusable by the current user — no
docker group membership, daemon not running — and a PATH check would happily
select it. Running info verifies in one shot that the binary exists, the
daemon/environment is healthy, and the current user has permission. The same
code is the preflight check, so probing and preflight can never disagree.
- Both usable →
docker, deterministically. BuildKit/buildx is the more mature ecosystem, and on a machine with both installed Docker is usually the one the user deliberately installed for daily use. Prefer podman? Say so explicitly. - Naming a runtime explicitly disables fallback. With
runtime: docker, an unavailable Docker is an error with remediation — tianluo will not quietly use podman instead. A silent switch changes the image cache, the storage location and UID-mapping behaviour behind your back, producing exactly the kind of "it worked yesterday" fault that is miserable to diagnose. - The probe result is fixed for the session. Every container operation in one run uses the same runtime; there is no mid-run switching.
A failed probe is reported as an environment problem with step-by-step
remediation (join the docker group / install podman / set up rootless Docker).
It is never treated as a code defect — see the failure routing below.
Content configuration lives in its own directory next to charter.md,
code-index.md and issues/, and is committed to git:
tianluo/e2e/
├── environment.yaml # services topology: base images, build steps, readiness probes
├── scenarios/
│ ├── cli-smoke.yaml # one scenario per file: driver + actions + assertions
│ └── api-smoke.yaml
└── baselines/ # git-tracked baseline screenshots for tier-2 diffs
Images are not committed — they are a regenerable cache, rebuildable from
zero out of this configuration. The project's source tree is bind-mounted into
the containers rather than COPY-ed into the images, so a fix-loop iteration
only restarts containers; images rebuild only when the build steps themselves
change.
The flow generates this directory on first use (when enabled is true but the
directory does not yet exist) and evolves it incrementally thereafter — it
adds and revises, it does not overwrite your hand edits. Evolution runs once per
flow, in the E2E step and before the scenarios execute, so a scenario added
for the behaviour this task introduced is exercised by the same run; fix-loop
iterations re-run the suite but never re-evolve it (a scenario is never rewritten
to make a failure go away). You can also drive it manually:
luo e2e bootstrap # generate / evolve the content directory
luo e2e list # list declared scenarios
luo e2e run # run them all
luo e2e run -s api-smoke # run one
luo e2e run --keep # leave the environment up for inspectionluo e2e run and the in-flow E2E step share one execution path, so manual
debugging and the flow behave identically. It exits 1 on a scenario failure,
3 on an environment problem and 4 on missing/inadmissible configuration.
A minimal single-service example — tianluo/e2e/environment.yaml:
network: tianluo-e2e
services:
- name: app
image: python:3.12-slim
base_kind: base # base | playwright | gui-xvfb
build:
- pip install --no-cache-dir -e .
readiness:
kind: command # command | http | tcp | log
command: ["python", "-c", "import myapp"]
timeout: 60Where a readiness probe runs matters. command probes execute inside the
container, so they see the shared network and can address peers by service name
(curl http://app:8000/health, pg_isready -h db). http and tcp probes are
dialled by tianluo itself, i.e. from the host, so they can only reach a port
the service publishes — ports: ["18000:8000"] plus
url: http://127.0.0.1:18000/health. Pointing an http probe at app:8000 or
at an unpublished localhost:8000 is rejected at validation time rather than
left to time out. An http probe accepts any 2xx/3xx answer by default; add
status: 401 when the service's healthy answer is a specific other code.
…and tianluo/e2e/scenarios/cli-smoke.yaml:
name: cli-smoke
driver: app # must name a service declared above
actions:
- action: exec
command: ["python", "-m", "myapp", "--version"]
assertions:
- kind: exit_code
equals: 0
- kind: stdout
contains: "myapp "Action order, and one rule about browser. Actions execute in declaration
order, with a single exception the validator makes impossible to hit by accident:
browser operations are collected into one Playwright program that runs
after the rest of the sequence (page state cannot survive a one-shot exec, so
batching is what keeps one browser session alive across the whole scenario).
Declaring a non-browser action after a browser one is therefore a
validation error — it would have run first, silently inverting the order you
wrote. Put every exec / http / wait ahead of the browser sequence, and take
in-page screenshots with a browser op: screenshot rather than the screenshot
action (which captures a virtual X display and belongs to a gui-xvfb driver).
An action that fails does not abort the sequence, but it is not free either. A
non-zero exec is recorded as a note and left to the assertions to judge — its
exit code and streams are exactly what exit_code / stdout / stderr exist
for, and a command that fails is frequently the thing under test. Everything else
(an unreachable http action, a wait.until that never came true, a coordinate
click that missed, a browser op that threw) has no assertion counterpart, so it
is reported as an action failure and the scenario cannot be reported as
passed — otherwise a broken UI whose assertions happen to look elsewhere would
come back green.
base_kind picks which bundled Dockerfile template is layered over image:
base (plain CLI / web / API), playwright (a browser driver — the official
image pins browsers, system libraries and fonts, which is what makes a tier-2
baseline reproducible), or gui-xvfb (Xvfb + a light window manager + scrot +
xdotool, so a desktop application can run and be screenshotted with no physical
display).
A scenario's driver must be able to perform what the scenario declares, and
that is checked at validation time: a browser action or a dom assertion needs
a browser, so the driver has to be a playwright service. Pointing such a
scenario at a base driver is a configuration error reported before anything is
built — otherwise the mismatch would only surface after every image was built and
every readiness probe awaited, aborting the run and discarding the results of the
scenarios that already passed in the same round.
The assertion ladder is enforced by the schema, not merely recommended.
Tier 1 is deterministic (exit_code, stdout, stderr, http_status,
http_body, file_exists, file_content, dom) and is the default, needing no
declaration. Tier 2 is screenshot_diff against a committed baseline and
requires visual_regression: true on the assertion. Tier 3 is
visual_semantic — an LLM looking at an image — and requires both
semantic_visual: true and require_evidence: true, because an LLM verdict is
admissible only alongside a reviewable description of what it saw. Escalating
past a tier that could have done the job is a validation error: a screenshot
comparison where a DOM query would do turns deterministic verification into
probabilistic verification. The same rule governs driving — clicking screen
coordinates (visual_click) is reserved for GUIs with no programmatic entry
point.
Getting the first tier-2 baseline. A baseline can only be produced inside the
image that renders the comparison shot — fonts and rasterisation live in the
image — so a new screenshot_diff starts with no file under baselines/. Run
luo e2e run --write-baselines once: it captures the missing images, reports the
scenario as not passed (nobody has looked at the rendering yet), and leaves it
to you to review the file and commit it. Without that flag a declared-but-absent
baseline is a configuration error naming the file, not a scenario failure — no
comparison happened, so blaming the code would be a lie.
A baseline: value must be a plain relative name inside baselines/ — no
absolute path, no ... Anything else is rejected at validation time: a path that
escapes the directory would be compared against (and, under
--write-baselines, written to) a file outside version control, quietly voiding
the "the baseline is a committed asset" contract.
When enabled is true, the E2E step is inserted immediately after test
and therefore before self_check: e2e is the coarse-grained counterpart of the
unit suite, so it runs on code that already passes the fine-grained one, and the
review layer then reads a diff whose behaviour has been exercised. Sequences with
no test step (review, survey) are left untouched — they produce no code
change for a scenario to exercise.
Failure routing is deliberately split in two:
- A failing scenario is a code defect. It returns
REVISION_NEEDEDand enters the ordinary fix loop underworkflow.max_fix_iterations, exactly like a failing unit test; once the budget is exhausted the run files an issue through the same fix-loop-exhaustion path. There is no discard, waiver, or severity-graded pass-through. - An environment problem is not. An unusable runtime, missing permissions, a failed preflight — these fail the step with remediation text and do not consume a fix iteration. Sending an LLM to "fix" a host with no Docker installed would burn the entire fix budget for nothing.
| Key | Type | Default | Meaning |
|---|---|---|---|
group_loc_threshold |
int | 300 |
[plan_decomposition: granular only] Total estimated LOC at or below which a multi-group task plan is merged into a single LLM call instead of being farmed out per group. Also feeds the sequential-vs-DAG-parallel decision above the threshold. Fail-fast, not clamp-and-warn (see below). |
use_worktree |
bool | true |
Whether implement groups run in isolated git worktrees. Accepts the usual boolean spellings; an unrecognised string falls back to the default rather than flipping behaviour. Overridable at runtime by the SE3_IMPLEMENT_USE_WORKTREE environment variable, which wins over the YAML value. |
group_loc_threshold applies to granular plans only. Under the default
capability doctrine the
threshold takes no part in either decision: a coarse capability group carries
no per-task estimated_loc, so the total would always be 0 — and 0 reads
as both "small enough to merge" and "not worth parallelising", which would
silently serialize groups the plan declared independent. Capability mode
dispatches on group count and topology instead: one group → the whole-task
implement call, two or more → the DAG path (plan_granularity: single pins
the whole-task call regardless of the count), still subject to the existing
use_worktree, linear-dependency-chain and no-commits short-circuits. The
threshold is skipped because a capability group carries no LOC estimate to
judge — not because every group is large: a capability group is one coherent
task, aggregated by default and split only at the capability edge, so it is
bounded by what a single autonomous call can carry but is not sized at that
ceiling (two mutually unrelated 20-LOC tasks legitimately produce two small
groups). Under granular the threshold behaves exactly as it always has.
group_loc_threshold is one of the explicit exceptions to the clamp-and-warn
rule: ImplementConfig.from_dict calls bare int(...) on the value with no
try/except, and its caller in the implement step does not guard it either.
A value that int() cannot parse — e.g. group_loc_threshold: "300 LOC" —
raises an uncaught ValueError out of ImplementConfig.load and fails the
implement step rather than falling back to 300. A float or bool is accepted
but silently truncated by int() (300.9 → 300, true → 1).
| YAML key | Dataclass field | Type | Default | Meaning |
|---|---|---|---|---|
steps.append |
StepConfig.append_steps |
list of strings | [] |
Step-type names appended to the end of the default step sequence. |
Note the name mismatch: the YAML key is append, the dataclass field is
append_steps. Writing steps.append_steps: in YAML does nothing.
steps:
append:
- summarizeEntries are validated against the StepType enum: an unknown name is silently
ignored (no warning), and a step already present in the sequence is not
duplicated. Appending is the only supported mutation — there is no steps.remove
or steps.replace.
Version-bump behaviour for the commit step. Loaded into
config.VersionConfig.
Naming trap. The YAML key for an explicit version-file path is
version_file, notfile_path.VersionConfig.from_dictreadsversion_data.get("version_file");.file_pathexists only as a read-only property alias on the dataclass (for duck-type compatibility withversion_bumper.VersionConfig) and is never read from YAML. Aversion: { file_path: … }in your config — including the one intianluo.example.yaml— is silently ignored.
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled |
bool | true |
Master switch for automatic version bumping in the commit step. |
version_file |
string or null | null |
Explicit path to the version file. null = auto-detect (pyproject.toml, package.json, …). |
include_in_commit_message |
bool | true |
Whether the commit message carries a Version: X.Y.Z trailer. |
script_path |
string or null | null |
Path to a project version script. null = the default tianluo/scripts/version.py. |
auto_generate_script |
bool | true |
Generate that script via LLM when it is not found. |
auto_bump |
bool | true |
Inert. No consumer in the engine — the bump is driven by version_analyze's suggested_version and gated by confirmation, not by this flag. |
confidence_threshold |
string or null | null |
Inert. Historically "medium" / "high" selected which confidence levels required human confirmation. |
prerelease_prefix |
string | "" |
Inert. |
prerelease_number |
int | 0 |
Inert. |
templates |
map | {readme_badge: …, versions_entry: …} |
Inert / legacy. Superseded by the documentation block, which is what DocumentationUpdater actually reads. Kept so old configs still parse. |
readme_enabled |
bool | true |
Inert. |
readme_marker |
string | "<!-- SE3-VERSION -->" |
Inert. |
versions_enabled |
bool | true |
Inert. |
versions_file |
string | "VERSIONS.md" |
Inert. |
versions_header |
string | "# Version History\n\n" |
Inert. |
Deprecated keys, accepted but ignored with a warning: bump_rules and
smart_version_analysis. Both were removed when the version decision model
collapsed to a single authoritative suggested_version produced by
version_analyze. To customize the bump rules, write natural-language rules
into tianluo/version-rules.md instead — that file is injected into the
version_analyze prompt; when absent, default SemVer 2.0.0 applies.
Note the split for worktree flows: a worktree session's commit is not its
release point, so it does not write the version file; the merge-side
version_reconcile step does.
Templates used by DocumentationUpdater when the commit step mechanically
updates README.md and VERSIONS.md. This is the block that actually drives
the updater, superseding the legacy version.templates.
| Key | Type | Default | Meaning |
|---|---|---|---|
readme_badge_template |
string |  |
Markdown written in place of the README version badge. |
versions_entry_template |
string | first ## block of the packaged versions_md.md template, else ## {{version}} - {{date}}\n\n{{changes}}\n |
The VERSIONS.md entry prepended for each release. An explicit config value is taken verbatim and not validated — one missing {{changes}} silently yields release entries with no changelog body. The {{version}} + {{changes}} requirement applies only to the packaged-file fallback: the first ## block of versions_md.md is accepted as a template only when it carries both, otherwise the built-in default is used. |
readme_header_template |
string | (unset) | Optional. When present, a version header line in the README is replaced too. Unset means the header pass is skipped entirely. |
Non-string values (and a non-mapping documentation: section) are dropped, so
the updater keeps its built-in defaults.
Placeholders are {{double-brace}} and are substituted by a plain string
replace. The context the commit step supplies is:
| Placeholder | Value |
|---|---|
{{version}} |
The new version string. |
{{date}} |
YYYY-MM-DD at render time. |
{{year}} |
Four-digit year at render time. |
{{changes}} |
(VERSIONS entry only) The rendered changelog bullets. |
Badge matching and insertion. update_readme looks for an existing badge
using, in order: a static shields-style  link, any
 link (case-insensitive), then an <img …version…> tag. The
first pattern that matches is replaced (count=1) with the rendered
template. If none matches, the rendered badge is inserted after the title
heading. The file is only written when the content actually changed.
The idempotent-no-op trick (used by this repository). Because the rendered
template replaces the matched badge verbatim, a template that contains no
{{version}} placeholder renders to a constant string. Once the README
already holds that exact string, the second pattern matches it, re.sub
substitutes it with itself, content == original_content, and nothing is
written — the badge rewrite becomes a byte-for-byte no-op, run after run.
This repository's root tianluo.yaml uses exactly that to
pin a shields.io dynamic badge that reads the version straight from
pyproject.toml, so the README carries no hardcoded version number and the
commit step never reverts it:
documentation:
readme_badge_template: ""Two details make this work and are worth preserving if you copy it: the alt text
must stay ![Version] (so the  pattern still finds it — otherwise
the updater finds no badge and inserts a second one), and the template must
not contain {{version}} (otherwise every release renders a different string
and the file is rewritten).
Knobs for building and rendering tianluo/code-index.md. All eight fields:
| Key | Type | Default | Meaning |
|---|---|---|---|
degrade_trigger_lines |
positive int | 2000 |
A structure-less, non-binary text file with at least this many lines becomes eligible for the line/byte chunk degrade mode (AST/structure boundaries are the normal granularity; chunking is the last resort). One of two size triggers — first to hit wins. |
degrade_trigger_bytes |
positive int | 262144 (256 KiB) |
Byte counterpart of degrade_trigger_lines. |
chunk_lines |
positive int | 200 |
When a file degrades to chunking, each chunk spans at most this many lines. |
chunk_bytes |
positive int | 16384 (16 KiB) |
Byte counterpart of chunk_lines — the first limit to hit cuts the chunk. |
exclude |
list of strings | [] |
Project-relative path patterns excluded from enumeration. Backstops the gitignore-based walk for tracked-but-unwanted noise git cannot filter (vendored blobs, huge generated files). Non-string / blank entries are dropped with a warning; a non-list value warns and yields []. |
view_budget_bytes |
positive int | 8192 (8 KiB) |
Byte budget for the adaptive root-view map injected into every flow step. Small on purpose: it bounds the always-injected orientation map and naturally stops expanding at directory granularity, which is the right altitude — function-level detail is pulled on demand via luo code-index show. |
primary_roots |
list of strings | [] |
Explicit top-level directory names whose subtree the adaptive root view drills into; the rest stay collapsed. [] = auto-detect the code-bearing top-level directories. Entries may be written with or without a trailing slash (src or src/); they are normalised to a trailing slash. |
max_concurrency |
positive int | 4 |
How many per-file LLM summarisation calls run concurrently during a (re)build. Conservative by default because the ceiling is LLM quota / rate-limit bound (the calls are I/O-bound, not CPU-bound); raise it to match your backend's limits. |
Every integer field is clamp-and-warn: a bool, a float, a non-integer, or a
non-positive value logs a warning and falls back to the default, so a malformed
code_index: never breaks an index rebuild.
Behaviour of the luo merge orchestrator.
| Key | Type | Default | Meaning |
|---|---|---|---|
strategy |
fast | safe | strict |
fast |
Conflict-resolution tier. fast: the LLM resolves conflicts; on failure the merge exits without invoking a human and never falls back to take-theirs (it inherits the old robust strategy's dirty-worktree stash behaviour). safe: the LLM resolves, and escalates to a human MCP call if it cannot converge. strict: every conflict goes straight to a human call, no LLM. |
delete_merged_default |
bool | true |
Whether luo merge deletes merged branches (and archives their worktrees) by default. Pass --no-delete-merged to opt out for one invocation. |
strict_runtime_sync |
bool | false |
Stricter reconciliation of runtime state during the merge. |
max_conflict_resolve_iterations |
int >= 1 |
10 |
Cap on LLM conflict-resolution rounds. < 1 → ConfigError; a non-integer warns and falls back to 10. |
The removed strategy names default and robust are not silently aliased —
they raise a ConfigError carrying a migration hint, so a stale config cannot
quietly change merge semantics. Migrate default → safe, robust → fast.
| Key | Type | Default | Meaning |
|---|---|---|---|
strategy |
human | llm |
human |
Conflict handling for loop-branch merges. human: preserve the conflict state, write a call file, wait for a human. llm: attempt per-file LLM resolution, falling back to human on failure. |
An unrecognised value is silently coerced to human (fail-safe, no error).
This block is distinct from merge: merge.strategy governs the
luo merge orchestrator, conflict_resolver.strategy governs the loop-branch
merge path.
Settings for the Claude CLI subprocesses tianluo spawns as workers.
| Key | Type | Default | Meaning |
|---|---|---|---|
setting_sources |
non-empty list of user | project | local |
["user"] |
Which Claude settings files the spawned CLI loads, passed through as --setting-sources <csv>. |
The ["user"] default isolates tianluo's workers from the target project's
.claude/settings.json, so permissions.deny rules aimed at that project's
own sub-LLMs cannot lock out tianluo's plan / implement / review children. Opt
back in explicitly with ["user", "project"].
This key is fail-fast: a non-list, an empty list, a non-string element, or
any value outside {user, project, local} raises ValueError at load time
rather than warning and defaulting. A non-mapping claude_subprocess: section
raises too.
Pitfall — duplicate
--settingsis last-wins. The Claude CLI's--settingsflag does not accumulate: a second occurrence anywhere later in argv wholly overrides the first, including themodelit selects. This bit this project once, when a guard appended its own--settingsafter an agent wrapper's — the wrapper's model was silently discarded and the run used the user settings' model instead. The engine therefore never appends a--settingsof its own. If your ownagents.<name>.cmdis a wrapper script that passes--settings, keep it the only one in the final argv. Note that--setting-sources(this config key) is a different flag with different semantics and is not affected.
Applies only to the optional central control plane (
pip install 'tianluo[server]', run via thetianluo-serverentry point). A core-only install never reads it at runtime. For deployment, TLS reverse proxying, bootstrapping the first admin, and daemon key issuance, see docs/daemon-and-server.md.
The server: block is a normal top-level key: a project server: section
wholly replaces the global one (no deep merge). Every field defaults, so a
server with no server: section still comes up usable.
| Key | Type | Default | Meaning |
|---|---|---|---|
db_path |
string | ~/.se3/server.db |
Path of the embedded sqlite store backing identity / auth. ~ is expanded at use. The tianluo-server --db-path flag overrides it for a single launch. |
auth |
map | (all defaults) | See below. |
history_cache |
map | (all defaults) | See below. |
Memory ceiling for the server's in-RAM history relay. The server mirrors each
active flow's whole conversation in process memory so the web console can be
served without a daemon round-trip, and daemons push that history for every
active flow whether or not a browser is watching it. Left unbounded, a long-lived
server in a memory-capped container (an LXC guest, a MemoryMax=-limited
service) is eventually OOM-killed. The budget bounds the mirror by evicting the
least-recently viewed bundle; an evicted flow is rebuilt from a full daemon
pull the next time a console opens it, so eviction costs one round-trip and never
loses records.
| Key | Type | Default | Meaning |
|---|---|---|---|
budget_mb |
int ≥ 0 | 256 |
Total budget, in MiB, for all cached history bundles together. 0 is valid and meaningful: only flows a console is actively reading stay resident. Negative / non-numeric values warn and fall back to the default. |
report_interval_seconds |
int ≥ 0 | 300 |
Cadence of the cache-occupancy diagnostic log line (total, budget, eviction counters, and the biggest cached flows by flow_id). 0 disables the periodic line; the over-threshold one still fires. This is a logging setting only — budget enforcement runs on its own fixed cadence and is never switched off by it. |
report_threshold_percent |
int ≥ 0 | 80 |
Occupancy percentage above which the same report is emitted at WARNING regardless of the cadence (debounced to at most one per minute). 0 disables the threshold trigger. |
Sizing note: the budget is a ceiling on cached bundles, not on the process. A bundle a console is actively reading is never evicted, so the real floor is "however many flows are open in browsers at once". Pair the budget with the systemd guardrails in docs/daemon-and-server.md.
| Key | Type | Default | Meaning |
|---|---|---|---|
providers |
list of local | oidc | proxy_header |
["local"] |
Ordered chain of auth providers to assemble. Unknown / blank / non-string entries are dropped with a warning; if nothing valid remains (or the value is not a list) it falls back to ["local"], so the server never comes up with an empty provider chain. Duplicates are collapsed. |
UI session cookie attributes. Defaults are fail-safe for a public deployment behind a TLS-terminating reverse proxy.
| Key | Type | Default | Meaning |
|---|---|---|---|
cookie_name |
non-empty string | se3_session |
Session cookie name. |
cookie_secure |
bool | true |
Set the Secure attribute. Leave on unless you are serving plain HTTP on localhost. |
cookie_httponly |
bool | true |
Set the HttpOnly attribute. |
cookie_samesite |
lax | strict | none |
lax |
SameSite attribute (compared lower-cased). An invalid value warns and falls back. |
max_age_seconds |
positive int | 86400 (24 h) |
Session lifetime. |
Brute-force guards for the built-in username+password provider. Two independent mechanisms: consecutive-failure lockout, and a sliding rate limit.
| Key | Type | Default | Meaning |
|---|---|---|---|
max_failed_attempts |
positive int | 5 |
Consecutive failures that lock the account. |
lockout_seconds |
positive int | 300 (5 min) |
How long the lock lasts. |
ratelimit_window_seconds |
positive int | 60 |
Sliding rate-limit window. |
ratelimit_max_attempts |
positive int | 10 |
Login attempts accepted per window. |
Each of these is clamp-and-warn on a bool, non-integer, or non-positive value — a typo cannot silently disable a lockout window.
A config seam for a future OIDC social-login provider; disabled by default
and not implemented in v1. When enabled is false the remaining fields are
inert.
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled |
bool | false |
Turn the provider on. |
issuer |
string or null | null |
OIDC issuer URL. |
client_id |
string or null | null |
|
client_secret |
string or null | null |
|
redirect_url |
string or null | null |
|
scopes |
non-empty list of strings | ["openid", "email", "profile"] |
An empty or malformed list warns and falls back to the default. |
A config seam for trusting a reverse-proxy-injected identity header; disabled by default, v1 ships the seam only.
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled |
bool | false |
Turn the provider on. |
trust_proxy |
bool | false |
Trust the upstream proxy's identity assertion. |
header |
non-empty string | X-Forwarded-Email |
Header carrying the identity. |
Security precondition when enabling this: the reverse proxy MUST strip any client-supplied copy of
header, and the server MUST NOT be reachable while bypassing the proxy. Otherwise the injected identity is forgeable and this is an authorization hole.
Named prompt templates for recurring tasks, run with luo run --preset <name>
(list them with luo run --preset list). Read by preset_loader, not by
config.py.
presets:
doc-sync:
type: feature
prompt_file: tianluo/prompts/doc-sync.md| Key | Type | Default | Meaning |
|---|---|---|---|
| (map key) | string | — | Preset name. |
type |
task type | the built-in default, or the existing entry's type | Task type the preset runs as (feature, bugfix, small, review, survey). |
prompt_file |
string | tianluo/prompts/<name>.md |
Path to the prompt Markdown, relative to the project root. |
Resolution is two-layered. Built-in presets ship inside the package and are read
at runtime (never copied by luo init), so upgrading tianluo picks up the
latest ones automatically. Project presets override built-ins by name, and are
themselves built from two sources: first a zero-config scan of
tianluo/prompts/*.md (file stem = preset name, default type), then this
presets: block, which overlays metadata onto that scan and may redirect a
preset to an arbitrary prompt_file. Declaring a preset here with neither a
prompt_file nor a matching tianluo/prompts/<name>.md resolves to the
conventional location and errors if it genuinely does not exist.
Some block names in older tianluo.yaml files date from the retired
spec-mirror era, when tianluo/specs/** was a governed mirror of the code.
That mirror has been retired — the code is the single source of truth, exposed
through the code-index, tianluo/charter.md, and colocated why-comments. The
spec_governance, spec_loading and spec_write_protection blocks (and
merge.guardrail_repair) no longer have a loader at all: an existing block is
simply ignored, and keeping it in your config is harmless but pointless.
tianluo.example.yaml still ships the two blocks below. The engine does not
read either of them — verified by grepping src/ for every key name and for
get("human_call") / a top-level get("session"); the only session hits are
the nested server.auth.session block and an unrelated JSON field in
engine/chat_history.py. They are retained in the sample for historical
continuity; configuring them has no effect.
| Block | Keys | Status |
|---|---|---|
human_call |
timeout_days, directory |
No reader. Human-call files are written to tianluo/calls/ at a path the runtime layout fixes, not this key. |
session |
progress_file, max_progress_entries |
No reader. |
An
e2eblock used to sit in this table too, carryingbaseline_dir,diff_threshold,default_viewportandtest_paths— four keys nothing ever read. The name has since been reclaimed by a real subsystem with an entirely different schema: seee2e. Those four legacy keys are not recognised by it and are ignored.
Suspect #1 is always Pitfall 1 —
a tianluo.local.yaml shadowing the file you edited. Check which file is
actually active:
python -c "
from pathlib import Path
from tianluo.config import get_project_config_path
print(get_project_config_path(Path('.')))
"If that prints a path you did not edit (note it may point into the main repo when you are inside a worktree), you found it.
Then print the resolved value of the block you care about — every loader is a plain function you can call:
python -c "
from pathlib import Path
from tianluo.config import (
load_workflow_config, load_investigation_config, load_docs_config,
load_code_index_config, load_merge_config, load_agents,
load_confirmation_config, load_language_config,
)
p = Path('.')
print(load_workflow_config(p))
print(load_investigation_config(p))
print(load_docs_config(p))
print(load_code_index_config(p))
print(load_merge_config(p))
print(load_agents(p))
print(load_confirmation_config(p))
print(load_language_config(p))
"Other loaders follow the same shape: TestConfig.load(p),
ImplementConfig.load(p), StepConfig.load(p), load_version_config(p),
load_server_config(p), load_claude_subprocess_config(p),
load_conflict_resolver_config(p),
load_step_agents(p, "implement"), load_self_check_resolution(p).
A checklist for the remaining cases:
- A YAML syntax error in
tianluo.local.yaml. It still shadowstianluo.yaml, and everything falls back to built-in defaults. The loader logs a one-shot warning naming the file — run with logging visible, or justpython -c "import yaml; yaml.safe_load(open('tianluo.local.yaml'))". - A per-step chain that swallowed your
defaultsedit. See Pitfall 2:llm_caller.steps.<step>never falls back. Confirm withload_step_agents(p, "<step>"). - The key name is wrong. The mismatches this codebase actually has:
steps.append(notappend_steps), andversion.version_file(notfile_path). Unknown keys are generally ignored in silence. - The block is inert or legacy. Cross-check against
Legacy / historical configuration and
the inert markers in the
versiontable. - The value was clamped or rejected. Most fields warn and fall back rather
than raising; the resolved value printed by the loader is the ground truth.
workflowadditionally logs its effective source once per config path:workflow config: max_fix_iterations=… (effective source: …). - An environment variable is winning.
SE3_IMPLEMENT_USE_WORKTREEoverridesimplement.use_worktree;SE3_LANGoutrankslanguage.languagefor CLI UI text. - You edited
tianluo.example.yaml. It is a shipped sample and is never read. Copy it totianluo.yamlfirst.