Guide

Leaf Authoring Guide

A useful Naoru leaf is a reliable autonomous repair signal: drives one narrow project check, judges the result with a machine-checkable predicate, and gives the fix worker enough focus to repair the failure without weakening the check. Any command can run; far fewer make a trustworthy RED/GREEN signal on their own.

This guide is stack-agnostic. Naoru does not know or care which language, framework, test runner, build system, or product shape a target repo uses. Project-specific interpretation belongs in the repo's own commands and wrapper scripts.

What Makes A Good Leaf

A good leaf has these properties:

• Narrow: one check, one reason to fail, one fix focus.
• Deterministic: the same repo state should produce the same RED/GREEN result.
• Machine-checkable: the predicate can decide pass/fail from exit status, output text, absence of a failure signature, non-crash status, or a measured metric.
• Non-interactive: does not wait for user input, credentials, external approvals, or manual inspection.
• Bounded: it has a sensible timeout_s or a check command that already exits predictably, and max_fix_loops is low for early dogfood passes.
• Focused: fix_focus tells the worker what system to repair and what not to weaken.

Avoid leaves whose success requires subjective judgment, live service state, unstable network calls, secrets, or broad "fix everything" commands. Use propose-only missions for subjective work.

Example shape:

[[leaves]]
id = "project-check"
command = ["./scripts/check_project"]
description = "Run the project-owned machine check."
fix_focus = "Make the project check pass without removing assertions or weakening validation."
timeout_s = 120
max_fix_loops = 1

[leaves.predicate]
kind = "exit_code"
expected_exit = 0

Wrapper Commands

Use a wrapper command when the raw project command is not itself a trustworthy leaf signal.

A wrapper is a project-local adapter that runs the real check, captures the relevant evidence, and exits or prints output in a form the leaf predicate can judge. Wrappers are the right place for project-specific quirks such as noisy logs, multi-step setup, report parsing, retry suppression, or translating a tool's domain-specific failure format into a clean process result.

Wrapper rules:

• Keep the wrapper in the target repo, not in Naoru.
• Preserve the raw command output that a maintainer needs to debug.
• Exit non-zero when the project is not in an acceptable state.
• Do not hide failures to make a leaf green.
• Keep wrapper behavior documented near the leaf set when it encodes project policy.

Naoru stays generic because the leaf only sees a command and a predicate:

[[leaves]]
id = "checked-project-load"
command = ["./scripts/check_project_safely"]
fix_focus = "Fix the project load failure without weakening the check wrapper."

[leaves.predicate]
kind = "exit_code"
expected_exit = 0

First-Run Procedure

Use this sequence for a new repo or a newly generated leaf set:

1. Start from a clean Git worktree.
2. Generate starter leaves if useful:

   naoru leaves generate --repo . --out .naoru/leaves.toml

1. Refine the generated leaves. Check command, predicate, fix_focus, timeout_s, enabled, and max_fix_loops.
2. Run a no-fix baseline:

   naoru run --mission test-and-fix-bugs --leaves .naoru/leaves.toml --repo . --max-fix-loops 0

1. Review RED, GREEN, and ERROR leaves. Add wrappers or adjust predicates when a raw command does not produce a trustworthy signal.
2. Run a bounded real pass. Keep max_fix_loops low until you trust the leaf set.
3. Run a final no-fix verification pass after any accepted fixes.

Generated leaves are starter seeds. They are not proof that the chosen command is the right autonomous repair signal.

Reading Results

Naoru reports one result per enabled leaf:

• green: the leaf already passed; no fix was attempted.
• fixed: a candidate patch passed the mission gate and was committed.
• proposed: a propose-only mission stored a patch for review.
• rejected: a candidate patch was refused by the gate and was not committed.
• error: the harness, command execution, leaf loading, or LLM setup failed.

rejected does not always mean the repo remains red. Another accepted fix can repair a shared underlying cause, so a later no-fix verification pass may show all leaves green even if some candidate patches were rejected during the real run.

Exit codes:

• 0: all enabled leaves are green, fixed, or proposed.
• 3: at least one candidate fix was rejected by a gate.
• 4: at least one leaf or harness operation errored.

LLM Authoring Prompt

Use this prompt when asking an LLM agent to author leaves for a repo:

Inspect this repository and propose a Naoru leaf set.

Constraints:
- Keep Naoru stack-agnostic: leaves are commands plus predicates.
- Use the repository's own checks or project-local wrapper commands.
- Create one narrow leaf per machine-checkable signal.
- Do not create leaves for subjective UX, visual quality, product taste, or manual review.
- Do not require secrets, live services, interactive input, or unstable network state.
- If a raw command can report success while still showing unacceptable failure evidence, propose a project-local wrapper that converts that evidence into a trustworthy exit code or output contract.
- For each leaf, include id, command, predicate, fix_focus, enabled, and max_fix_loops.
- Keep max_fix_loops low for the first dogfood pass.
- Explain why each leaf is machine-checkable and what failure it is meant to repair.
- Recommend a no-fix baseline run before any real fix loop.

Return TOML or JSON loadable by Naoru's leaf parser.