kusaw.yaml
Version 2 factory configuration. This schema is embedded in the kusaw binary and is never fetched.
kusaw.yaml
Version 2 factory configuration. This schema is embedded in the kusaw binary and is never fetched.
Generated from the schema embedded in the kusaw binary. Do not edit by hand.
access
Declared MCP servers, skills, environment allowlist and redact patterns.
type object.
access.defaults
MCP servers and skills used when a step omits its own lists.
type object. default {"mcp":[],"skills":[]}.
access.defaults.mcp
Default MCP server names.
type array. default [].
access.defaults.skills
Default skill names.
type array. default [].
access.env
Factory-wide environment allowlist.
type object.
access.env.allow
Exact names or trailing-star prefixes passed to every step.
type array. default [].
access.mcp_servers
Named MCP servers. Each has a command or a URL.
type object. default {}. each entry is mcpServer.
access.redact
Patterns stripped from logs, events and artifacts.
type object.
access.redact.patterns
Regular expressions. A pattern must not match empty text.
type array. default [].
access.skills
Named skill folders, each containing SKILL.md.
type object. default {}. each entry is skill.
allowed_providers
Factory-level provider allowlist. Can only narrow the machine's user-level list in registry.yaml; it cannot enable Cursor by itself. Omitted means no further narrowing.
type array.
atlas
Local codebase map and code index. Omitted keys use the defaults. No Atlas exists until kusaw atlas build.
type object.
atlas.agents
When on, agent steps may use Atlas tools.
type string. one of "on", "off". default "on".
atlas.auto_refresh
When on, Atlas refreshes from local main while serve runs.
type string. one of "on", "off". default "on".
atlas.auto_refresh_max_usd
Dollar cap for automatic refreshes.
type number. default 1.
atlas.chunker
How files are split. Built-in symbols, or a protocol v2 command.
see atlasTool.
atlas.embedding
Optional embedding. Unset means keyword-only search. The factory ships no model.
see atlasEmbedding.
atlas.exclude
Glob paths skipped by the indexer.
type array. default [].
atlas.map
How map pages are written. Built-in atlas-map, or a protocol v2 command.
see atlasMap.
atlas.max_file_kb
Files larger than this are too_large, from 16 to 4096.
type integer. default 512.
atlas.modules
Override detected modules. When set, these modules are used instead of detection.
type array.
each item is atlasModule.
atlas.overview_cap_tokens
Token cap for the overview page, from 500 to 8000.
type integer. default 2000.
atlas.repos
Repo labels to index. Default is every repo in repos.
type array.
atlas.scanner
Secret scanner. Built-in betterleaks, or a protocol v2 command.
see atlasTool.
atlas.secret_scan
on (default) scans before indexing. off is the only way to build without a scanner.
type string. one of "on", "off". default "on".
claude
How built-in steps start Claude Code.
type object. default {"command":"claude","extra_args":[],"env_passthrough":["CLAUDE_*"]}.
claude.command
Claude Code executable. The factory passes no credentials.
type string. default "claude".
claude.env_passthrough
Environment names or prefix globs passed only to Claude Code steps.
type array. default ["CLAUDE_*"].
claude.extra_args
Extra Claude Code arguments. A bare "--" is rejected; the factory adds it before the interactive first message.
type array. default [].
connectors
User-declared MCP or command connectors the factory polls and exposes to steps (GF-115). At most 20. Names match ^[a-z][a-z0-9-]{0,31}$.
type object. default {}. each entry is connector.
cursor
Cursor provider settings. Mirrors claude: command, extra_args, and env_passthrough, plus pricing separate from Claude Code. The factory ships no prices or model names.
type object.
cursor.command
Cursor CLI executable. Unset means agent, then cursor-agent.
type string. default "agent".
cursor.env_passthrough
Environment names or prefix globs passed only to Cursor steps.
type array. default ["CURSOR_API_KEY"].
cursor.extra_args
Extra Cursor CLI arguments. Only flags are allowed; runner-owned flags are refused.
type array. default [].
cursor.pricing
Optional per-model Cursor token prices. Same shape as pricing.. The factory ships none; docs use placeholders such as .
type object. default {}. each entry is price.
data_dir
Directory for the database, runs, worktrees, specs and Atlas files. Relative paths are beside kusaw.yaml.
type string. default ".kusaw".
default_workflow
Workflow used when classify is off or there is one workflow.
type string.
effects
User-declared command effect kinds (GF-92). Kind names are lowercase, dot-separated, at least two parts, and must not start with run. or proposal.
type object. default {}. each entry is effectKind.
finally
Stages that run after the pipeline, including after failure.
type array. default [].
each item is stage.
improve
Grouping and drafting of self-improvement proposals. Nothing is applied without approval.
type object. default {"window_days":30,"min_runs":3,"budget_usd_per_day":1}.
improve.budget_usd_per_day
Dollars available for drafting proposals each local day. 0 turns drafting off.
type number. default 1.
improve.min_runs
Distinct runs required before a group is drafted. From 2 to 20.
type integer. default 3.
improve.window_days
How many days of signals are grouped. From 7 to 180.
type integer. default 30.
intake
Interactive stages run by kusaw intake.
type array. default [].
each item is stage.
limits
Per-run time and budget.
type object. default {"run_minutes":30,"budget_usd_per_run":5,"finally_budget_usd":0.5,"max_attempts":4}.
limits.budget_tokens_per_run
Token budget for pipeline attempts. Cached reads count at a fraction of input (the attempt's provider price ratio, or 0.1). Unset means no token budget. Cursor reports usage only at the end of a step, so a Cursor step can overshoot by up to one step. Time limits still apply during the step.
type integer.
limits.budget_usd_per_run
Dollar budget shared by pipeline steps.
type number. default 5.
limits.finally_budget_tokens
Token budget for finally attempts, including scorers. Cached reads count at a fraction of input. Unset means none. Cursor can overshoot by up to one step.
type integer.
limits.finally_budget_usd
Separate dollar allowance for finally steps.
type number. default 0.5.
limits.max_attempts
Maximum attempts in a candidates stage (2-8). Missing or 0 means 4.
type integer. default 4.
limits.run_minutes
Active minutes allowed for a run. Paused, waiting and asleep time do not count.
type integer. default 30.
metrics
Run-metric settings.
type object.
metrics.size_buckets
Inclusive line-count limits keyed by labels of 1 to 3 capital letters, in increasing order.
type object. default {"XS":10,"S":50,"M":300,"L":1000}.
monitor
Watchdog and control poll.
type object. default {"stuck_after_minutes":30,"control_poll_seconds":2}.
monitor.control_poll_seconds
Seconds between heartbeat and control-request polls.
type integer. default 2.
monitor.stuck_after_minutes
Minutes without progress before a step is treated as stuck.
type integer. default 30.
name
Factory name. When omitted, an unregistered file uses its folder name.
type string.
order
Work order settings. order.intake is the planning list for kusaw order new. Readiness probes run before approval and with kusaw order ready. Milestone checks run after integration. Failed checks become fix runs up to order.max_fix_rounds.
type object.
order.checks
Milestone checks run after integration. Default is contract-review and contract-tests. Each entry is a step that lists milestone_check in its handshake.
type array. default [{"name":"contract-review","step":"contract-review"},{"name":"contract-tests","step":"contract-tests","config":{"report":"build/test-report.xml"}}].
each item is orderCheck.
order.intake
Planning steps run by kusaw order new. Default is grill (config.mode order), write-plan, and plan-check. Each entry is a step id or a mapping with step or command.
type array. default [{"step":"grill","config":{"mode":"order"}},{"step":"write-plan"},{"step":"plan-check"}].
each item is orderIntake.
order.max_fix_rounds
How many fix runs a milestone may try after a failed check, including a merge-conflict fix. Default 3. Range 1 to 5.
type integer. default 3. from 1 to 5.
order.readiness
Probes run at the base before approval. Default is the built-in test-command probe. A custom entry is a command step run with protocol mode check.
type array. default [{"step":"test-command"}].
each item is readinessProbe.
order.readiness_timeout
How long each readiness probe may run, as a Go duration. Default 15m.
type string. default "15m".
order.test_command
Test command used by the built-in test-command probe and by contract-tests. A string applies to every repo; a map is keyed by repo label. Falls back to steps.build.config.test_command.
outcomes
Local labelling of delivered commits.
type object.
outcomes.check_every
How often to label delivered commits, as a Go duration.
type string.
outcomes.land_window_days
Days after delivery during which a land is still counted.
type integer.
outcomes.rework_days
Days after delivery during which a follow-up change counts as rework.
type integer.
pipeline
Unattended stages for a queued run.
type array. default [].
each item is stage.
plan
Planner limits (GF-126).
type object.
plan.max_subtasks
Maximum subtasks a plan may return. Default 6, at most 12.
type integer. default 6.
ports
Machine-wide port blocks leased to each worktree set (GF-131). Without this mapping nothing is allocated. Defaults when set: range 20000-29999, block 10.
type object.
ports.block
Ports per worktree set, from 2 to 50. Default 10 when ports is set.
type integer. default 10. from 2 to 50.
ports.names
Optional names for the first ports of the block (^[a-z][a-z0-9_]{0,15}$). At most block names. Exposed as KUSAW_PORT_.
type array. default [].
ports.range
Inclusive lo-hi port range inside 1024-65535. Default 20000-29999 when ports is set.
type string. default "20000-29999".
pricing
Optional per-model Claude Code token prices. Cursor prices go in cursor.pricing..
type object. default {}. each entry is price.
provider
Factory default agent provider for pipeline and finally steps. Intake always runs on claude-code. Omitted means claude-code.
type string. one of "claude-code", "cursor". default "claude-code".
reporting
Local deny override for first-party anonymous usage and error reports. This is not an opt-in and is independent of telemetry.
type object.
reporting.disabled
When true, this factory sends no first-party reports and suppresses reporting prompts. Environment KUSAW_REPORTING=off is the stronger per-process deny.
type boolean. default false.
repos
Labelled checkouts. At least one repo is required.
type object. at least 1. each entry is repo.
routing
How a new task is assigned a workflow (GF-114).
type object.
routing.classify
Classify provider used when no rule matches.
type object.
routing.classify.provider
agent (default), command, or off.
type string. default "agent".
routing.classify.step
Optional steps. whose provider, timeout and config are used.
type string.
routing.classify.threshold
Minimum confidence to auto-route. Default 0.80, from 0.50 to 1.00.
type number. default 0.80.
routing.rules
First matching rule wins. At most 50.
type array. default [].
each item is routingRule.
sandbox
OS-native process sandbox for agent and custom steps (GF-88). Default off. Backend is chosen by the OS: seatbelt on macOS, bwrap on Linux and WSL2.
type object. default {"mode":"off"}.
sandbox.allow_read
Extra readable paths, absolute or starting with ~/. Never the home folder, /, the secret store, ~/.ssh or ~/.gnupg.
type array. default [].
sandbox.allow_write
Extra writable paths, for example a shared tool cache.
type array. default [].
sandbox.egress
see sandboxEgress.
sandbox.mode
off (default) or required. A required attempt never runs unsandboxed.
type string. one of "off", "required". default "off".
sandbox.network
open (default, GF-88) or allowlist (GF-132). allowlist is opt-in.
type string. one of "open", "allowlist". default "open".
scorecard
Factory-wide attempt scorecard defaults (GF-146). A candidates stage may override them.
see scorecard.
scorers
Opt-in judges that score a finished run.
type array. default [].
each item is scorer.
scorers_defaults
Defaults for every scorer, including calibration thresholds.
type object.
scorers_defaults.calibration
see calibration.
services
Factory-level service policy (GF-131). Repo services are repos..services.
type object.
services.stop_at_gate
When true, declared services stop while a run waits at a gate. Default false: they keep running so a reviewer can open the app.
type boolean. default false.
sessions
Provider session resume. resume_max_age_hours is how old a recorded session may be before kusaw resume --failed-only --resume-session starts fresh (GF-101).
type object. default {"resume_max_age_hours":72}.
sessions.resume_max_age_hours
Hours a recorded provider session stays resumable. Default 72. Range 1 to 720. Older sessions start fresh (E2).
type integer. default 72. from 1 to 720.
signing
Signed deliveries (GF-87). timeout is every signing call; unlock_ttl is how long kusaw signing unlock asks the agent to keep the key.
type object. default {"timeout":"30s"}.
signing.timeout
Deadline for every factory signing call. Default 30s.
type string. default "30s".
signing.unlock_ttl
Optional lifetime passed to ssh-add -t on platforms that support it.
type string.
steer
Live steering. When live is true and Claude Code accepts streaming input, notes are sent into the running step (GF-133). Default false (Q99).
type object. default {"live":false}.
steer.live
When true, and Probe finds streaming input, Claude Code starts with --input-format stream-json and stdin stays open for notes. Default false.
type boolean. default false.
steps
Named step definitions. An id is lowercase letters, digits and dashes.
type object. default {}. each entry is step.
telemetry
Opt-in metadata export. Off unless enabled is true. The endpoint is chosen by the operator; there is no vendor default.
type object.
telemetry.audit_keep_days
How long to keep local audit files, from 30 to 3650 days.
type integer. default 365. from 30 to 3650.
telemetry.buffer_max_mb
Outbox cap in megabytes, from 1 to 1024.
type integer. default 50. from 1 to 1024.
telemetry.enabled
Send metadata only when true.
type boolean. default false.
telemetry.endpoint
HTTPS ingest URL. http is accepted only for 127.0.0.1 or localhost.
type string. default "".
telemetry.factory_label
Optional label sent in clear. Empty sends none.
type string. default "".
telemetry.level
The only accepted level in this version is metadata.
type string. one of "metadata". default "metadata".
telemetry.send_every
How often to send a batch, from 10s to 1h.
type string. default "60s".
telemetry.signing_key_env
Name of the env var that holds the HMAC signing key. The key is never written here.
type string. default "KUSAW_TELEMETRY_SIGNING_KEY".
telemetry.token_env
Name of the env var that holds the bearer token. The token is never written here.
type string. default "KUSAW_TELEMETRY_TOKEN".
triage
Stages run by kusaw triage. Plain step entries only.
type array. default [].
each item is stage.
triggers
Schedules and inbox folders that queue work while serve runs.
type object.
triggers.inbox
Folders polled for spec files.
type array.
each item is inbox.
triggers.schedules
Cron schedules that queue a spec template.
type array.
each item is schedule.
version
Factory file version. This factory reads version 2.
type integer.
worker
Worker concurrency.
type object. default {"max_parallel":3,"completion_grace_seconds":60}.
worker.completion_grace_seconds
Seconds to wait after a step prints its result for the process to exit. Default 60. Range 5–600.
type integer. default 60. from 5 to 600.
worker.max_parallel
Factory-wide cap on runs and extra parallel work (feature, check and fix runs, candidate attempts, fanout subtasks, parallel group members). Default 3.
type integer. default 3. from 1 to 8.
workflows
Named workflows (GF-114), or list-form sub-pipelines fanout.workflow can point at.
type object. default {}.
worktrees
Worktree reuse and prune. keep_days is how long finished delivered or cancelled run worktrees are kept before kusaw worktrees prune (GF-97).
type object. default {"keep_days":7}.
worktrees.keep_days
Days to keep worktrees of finished delivered or cancelled runs. Default 7. Prune never touches needs_attention, taken-over runs, live locks, or salvage and backup refs.
type integer. default 7. from 1 to 3650.
Types
atlasEmbedding
Embedding provider for Atlas. provider is local or a provider this factory already uses for model calls.
type object.
atlasEmbedding.command
Argv of the embedder. model and dims are required when this is set.
type array.
atlasEmbedding.dims
Embedding width.
type integer.
atlasEmbedding.model
Label stored with the vectors.
type string.
atlasEmbedding.provider
local (default) or a provider already used for model calls.
type string. default "local".
atlasMap
How Atlas map pages are written. Built-in atlas-map on the resolved provider, or a protocol v2 command.
type object.
atlasMap.builtin
Built-in name. Default atlas-map.
type string.
atlasMap.command
Argv of a user program, run through step protocol v2 with mode atlas_map.
type array.
atlasMap.model
Model the built-in map writer passes to the provider. Omitted uses the provider default.
type string.
atlasMap.page_input_tokens
Per-page input token cap for the map writer, from 1000 to 500000. Default 60000.
type integer. default 60000.
atlasMap.parallel
How many module pages to write at once, from 1 to 8. Default 2.
type integer. default 2.
atlasMap.provider
Agent provider for the built-in map writer: claude-code or cursor. Omitted uses the factory default.
type string.
atlasModule
One named module that overrides detection.
type object.
atlasModule.name
Module name and page slug.
type string.
atlasModule.paths
Snapshot-relative path prefixes this module covers.
type array.
atlasTool
A built-in Atlas tool or a replacement command.
type object.
atlasTool.args
Extra flags for the built-in scanner. Detection-only; validation, analysis, and revocation are refused.
type array.
atlasTool.builtin
Built-in name.
type string.
atlasTool.command
Argv of a user program, run through step protocol v2.
type array.
atlasTool.path
Executable path for the built-in scanner. Default is the builtin name on PATH.
type string.
calibration
How many labels and how much agreement a scorer needs before GF-34 uses its failures.
type object.
calibration.min_agreement
Agreement with labels required to be calibrated, from 0 to 1. Default 0.80.
type number.
calibration.min_labels
Labels (pass or fail, with a scored result) required before a scorer can be calibrated. Default 20.
type integer.
candidateAttempt
One labelled attempt on a candidates stage (GF-145).
type object.
candidateAttempt.label
Short unique name used in branches and refs. Lower-case letters, digits and -, at most 24 characters.
type string.
candidateAttempt.limits
Optional GF-129 limits overlay for this attempt.
type object. extra keys allowed.
candidateAttempt.model
Optional provider-native model setting. The factory ships no model names.
type string.
candidateAttempt.provider
Optional provider for this attempt: claude-code or cursor.
type string.
candidateAttempt.steps
Optional GF-129 steps overlay for this attempt.
type object. extra keys allowed.
candidateAttempt.worker
Optional GF-129 worker overlay for this attempt.
type object. extra keys allowed.
candidates
A best-of-N stage (GF-129). Runs a workflow 2 to 4 times. mode pick (default) selects a winner; mode compare scores every attempt and delivers the baseline, or nothing. attempts may replace count and variants.
type object.
candidates.apply_to
Step ids in the candidate workflow that receive each attempt's provider and model. Default: every agent-backed built-in in that workflow.
type array. default [].
candidates.attempts
Labelled provider and model overlays, one per candidate. Replaces count and variants when set. 2 to 4 entries.
type array. default [].
each item is candidateAttempt.
candidates.baseline
Attempt label to gather in compare mode. Omitted delivers nothing.
type string.
candidates.count
How many candidates to run. Must be between 2 and the attempt limit (4). Default 2. Ignored when attempts is set.
type integer. default 2. from 2 to 4.
candidates.mode
pick (default) runs the select step. compare scores every attempt and delivers the baseline, or nothing.
type string. one of "pick", "compare". default "pick".
candidates.name
Name used in key paths and logs.
type string.
candidates.regrade
When true, also take a clean grade per candidate. Default false. Clean-checkout regrade is not implemented on this branch.
type boolean. default false.
candidates.scorecard
Per-stage scorecard. Overrides factory scorecard defaults.
see scorecard.
candidates.scorers
Scorer names to run on each candidate's diff. They affect select only when listed.
type array. default [].
candidates.select
Optional command step id that picks the winner. Omitted uses the built-in select.
type string.
candidates.variants
Optional overlays, one per candidate. Same keys as a benchmark variant (steps., limits., worker.*, provider, model). Missing entries use the parent config. Mutually exclusive with attempts.
type array. default [].
candidates.workflow
Name of a workflows: sub-pipeline to run for each candidate.
type string.
commandEnv
How this repo's setup, test and verification commands run.
type object.
commandEnv.env_allow
Extra environment names or trailing-star prefixes for this repo's factory commands.
type array.
commandEnv.expose_env_to_steps
When true, agent sessions in this repo also receive env_allow. Custom steps still need command_env: repo. Default false.
type boolean. default false.
commandEnv.secret_names
Extra names whose wrapper-injected values are redacted.
type array.
commandEnv.shell
sh, bash, or an absolute path to a POSIX shell. Default sh.
type string.
commandEnv.shell_init
Lines run in the same shell as the command, in order. 1 to 20 lines.
type array.
commandEnv.wrap
Argv prefix every command runs under, for example a secrets CLI.
type array.
connector
One named connector. Exactly one of mcp or command.
type object.
connector.agent_tools
Read tools agents may call through factory-connectors.
type array.
connector.command
Argv of a protocol-1 command connector.
type array.
connector.context
Named context files written into each attempt.
type object. each entry is connectorToolCall.
connector.docs
Read-only document store context (GF-118).
see connectorDocs.
connector.intake
Poll mapping while serve runs.
see connectorIntake.
connector.logs
Log-store context and severity-based work items (GF-117).
see connectorLogs.
connector.max_calls_per_attempt
Maximum agent connector calls per attempt. Default 50.
type integer. default 50.
connector.mcp
MCP transport (stdio command or streamable HTTP url).
see connectorMCP.
connector.timeout
Tool call timeout as a Go duration. Default 30s.
type string. default "30s".
connector.tracker
Two-way status sync for a tracker connector (GF-116).
see connectorTracker.
connector.write_back
Write-back tools held as outside effects.
type object. each entry is connectorToolCall.
connectorAgentTool
One agent_tools entry. A bare string is the tool name.
type object.
connectorAgentTool.allow_unmarked
Allow this agent tool even when the server does not mark it read-only. Still warns (W2).
type boolean.
connectorAgentTool.tool
Tool name on the connector.
type string.
connectorDocs
Document store mapping. A docs connector cannot declare intake or write_back.
type object.
connectorDocs.fixed
Document ids fetched for every run of steps that ask.
type array.
connectorDocs.get
Tool that fetches one document by id.
see connectorDocsGet.
connectorDocs.link_hosts
URL hosts in the spec that name a task document.
type array.
connectorDocs.link_id
Regular expression with one capture group that takes the id from a matching link.
type string.
connectorDocs.refresh
When to refetch. Default is once per run; attempt fetches every attempt.
type string. one of "run", "attempt".
connectorDocs.search
Tool that searches documents for this task.
see connectorDocsSearch.
connectorDocsGet
docs.get mapping. Reuses the tool-call shape plus field paths.
type object.
connectorDocsGet.args
Arguments, rendered with the strict template engine. Use {{doc.id}} for the document id.
type object. extra keys allowed.
connectorDocsGet.fixed
Arguments the core always sends.
type object. extra keys allowed.
connectorDocsGet.required
A missing document named by the task ends the attempt when true (default).
type boolean. default true.
connectorDocsGet.text
Dotted path of the document text. Default is the first text content.
type string.
connectorDocsGet.title
Dotted path of the document title.
type string.
connectorDocsGet.tool
Tool name on the connector.
type string.
connectorDocsGet.url
Dotted path of the document URL.
type string.
connectorDocsSearch
docs.search mapping.
type object.
connectorDocsSearch.args
Arguments, rendered with {{task.title}} and {{task.labels.}}.
type object. extra keys allowed.
connectorDocsSearch.fixed
Arguments the core always sends.
type object. extra keys allowed.
connectorDocsSearch.id
Dotted path of each result's id.
type string.
connectorDocsSearch.max_results
Keep the first N results (default 5, at most 10) and fetch each with get.
type integer. default 5. from 1 to 10.
connectorDocsSearch.required
A failed search ends the attempt when true (default).
type boolean. default true.
connectorDocsSearch.results
Dotted path of the results array.
type string.
connectorDocsSearch.tool
Search tool name on the connector.
type string.
connectorIntake
Poll mapping while serve runs.
type object.
connectorIntake.args
Arguments, rendered with the strict template engine.
type object. extra keys allowed.
connectorIntake.every
Poll interval from 1m to 24h. Default 10m.
type string. default "10m".
connectorIntake.interval
Alias of every.
type string.
connectorIntake.item
Field mapping from a poll result onto an item.
see connectorItemMap.
connectorIntake.mode
hold (default) or queue.
type string. one of "hold", "queue". default "hold".
connectorIntake.spec_template
Optional spec body template for queued items.
type string.
connectorIntake.tool
Tool to call each poll.
type string.
connectorItemMap
Dotted paths from a poll result onto an item.
type object.
connectorItemMap.body
Dotted path of the body, cut to 20,000 characters.
type string.
connectorItemMap.id
Dotted path of the item id. Required.
type string.
connectorItemMap.labels
Dotted path of labels.
type string.
connectorItemMap.status
Dotted path of the tracker status, or a list of paths whose non-empty values are joined with ':'.
connectorItemMap.title
Dotted path of the title. Required.
type string.
connectorItemMap.type
Dotted path of the item type.
type string.
connectorItemMap.updated
Dotted path of the updated timestamp.
type string.
connectorItemMap.url
Dotted path of the source URL.
type string.
connectorLogEventMap
Dotted paths from a poll result onto a log event.
type object.
connectorLogEventMap.count
Dotted path of the occurrence count.
type string.
connectorLogEventMap.first_seen
Dotted path of first_seen.
type string.
connectorLogEventMap.group
Store grouping id. Fingerprint is ext: plus this value.
type string.
connectorLogEventMap.id
Dotted path of the event id. Required.
type string.
connectorLogEventMap.kind
Dotted path of the error kind or type.
type string.
connectorLogEventMap.last_seen
Dotted path of last_seen.
type string.
connectorLogEventMap.level
Dotted path of the level or status.
type string.
connectorLogEventMap.message
Dotted path of the message. Required.
type string.
connectorLogEventMap.service
Dotted path of the service name.
type string.
connectorLogEventMap.stack
Dotted path of the stack trace.
type string.
connectorLogEventMap.url
Dotted path of the store link.
type string.
connectorLogMatch
logs.rules[].when. All set fields must match.
type object.
connectorLogMatch.kind
Match if the kind is in this list.
type array.
connectorLogMatch.level
Match if the event level is in this list.
type array.
connectorLogMatch.message
Match if the message contains one of these substrings.
type array.
connectorLogMatch.min_count
Minimum count, optionally in window.
type integer. at least 1.
connectorLogMatch.service
Match if the service equals an entry or a * prefix.
type array.
connectorLogMatch.window
Duration window for min_count.
type string.
connectorLogRule
One ordered severity rule.
type object.
connectorLogRule.severity
Severity when when matches.
type string. one of "critical", "high", "medium", "low".
connectorLogRule.when
see connectorLogMatch.
connectorLogs
Log-store context and severity-based work items.
type object.
connectorLogs.create_for
Severities that create a work item. Default [critical].
type array. default ["critical"].
connectorLogs.errors
Read use that polls error groups.
see connectorLogsErrors.
connectorLogs.items
hold (default) stores a held connector item; queue opts in to queue.Add. Independent of intake.mode.
type string. one of "hold", "queue". default "hold".
connectorLogs.reopen_after
Recurrence window after the fingerprint's task ended. Default 24h.
type string. default "24h".
connectorLogs.repos
Repo labels for queued log items. Default all factory repos.
type array.
connectorLogs.rules
Ordered severity rules. First match wins; no match is low.
type array.
each item is connectorLogRule.
connectorLogs.spec_template
Optional spec body template for log items (GF-104).
type string.
connectorLogsErrors
logs.errors poll mapping.
type object.
connectorLogsErrors.args
Arguments, rendered with the strict template engine.
type object. extra keys allowed.
connectorLogsErrors.event
Dotted paths from a poll result onto a log event. id and message are required.
see connectorLogEventMap.
connectorLogsErrors.every
Poll interval from 1m to 24h. Default 5m.
type string. default "5m".
connectorLogsErrors.interval
Alias of every.
type string.
connectorLogsErrors.tool
Tool to call each poll.
type string.
connectorMCP
MCP transport for a connector. Exactly one of command or url.
type object.
connectorMCP.command
Argv of a stdio MCP server.
type array.
connectorMCP.env
Environment for a stdio MCP command. Each entry is {value} or {secret: true}.
type object. each entry is envEntry.
connectorMCP.headers
HTTP headers for a url MCP server. Each entry is {value} or {secret: true}.
type object. each entry is envEntry.
connectorMCP.url
Streamable HTTP MCP URL.
type string.
connectorToolCall
One mapped tool call with optional args.
type object.
connectorToolCall.args
Arguments, rendered with the strict template engine.
type object. extra keys allowed.
connectorToolCall.fixed
Arguments the core always sends and that no effect can change (for example method: update).
type object. extra keys allowed.
connectorToolCall.required
For context tools, a failed call ends the attempt when true (default).
type boolean. default true.
connectorToolCall.tool
Tool name on the connector.
type string.
connectorTracker
Status mapping and write-back moments for a tracker connector.
type object.
connectorTracker.args
Dot-path mapping from factory argument names (id, status, body, url, title) onto the tool's input names.
type object.
connectorTracker.comment_on
Moments that propose a comment effect.
type array.
connectorTracker.comment_templates
Optional comment templates keyed by moment. Unknown placeholders are an error.
type object.
connectorTracker.link_on
Moments that propose a link effect (or embed the link in the comment when there is no link tool).
type array.
connectorTracker.out
Factory moment to tracker value. Omitted moments write nothing.
type object.
connectorTracker.status_args
Arguments sent to set_status for a tracker value. Default {status: }.
type object.
connectorTracker.statuses
Tracker value to factory meaning: todo, in_progress, in_review, done, cancelled. Unmapped values are other.
type object.
effectKind
One user-declared command effect kind (GF-92).
type object.
effectKind.apply
Argv of the applier. Resolved like command steps. Runs in the factory folder.
type array.
effectKind.apply_at
step applies after the step succeeds; delivery waits until delivery succeeds.
type string. one of "step", "delivery". default "step".
effectKind.constraints
Named checks. in_diff requires args.path and args.line to be in the run's diff.
type array.
effectKind.dry_run
Argv used for dry-run preview. Runs in the factory folder.
type array.
effectKind.env
Environment for the applier. Each entry is {value} or {secret: true}. Secrets never reach the agent session.
type object. default {}. each entry is envEntry.
effectKind.max_per_run
Maximum accepted effects of this kind in one run.
type integer. at least 1.
effectKind.on_invalid
reject drops the whole result; drop drops only failing effects of this kind.
type string. one of "reject", "drop". default "reject".
effectKind.schema
JSON Schema file for args, relative to the factory folder.
type string.
effectKind.scope
outside (default) waits for a human gate; local applies after the step.
type string. one of "outside", "local". default "outside".
effectKind.timeout_seconds
Applier timeout. Default 60.
type integer. default 60. at least 1.
envEntry
A visible config value, a secret, or a plain string (invalid).
fanout
A plan-driven sub-pipeline stage (GF-126).
type object.
fanout.fail_fast
Stop independent subtasks at the first failure. Default false.
type boolean. default false.
fanout.keep_branches
Keep subtask branches after the run ends. Default false.
type boolean. default false.
fanout.max_parallel
How many subtasks may run at once. Omitted uses worker.max_parallel.
type integer.
fanout.name
Name used in key paths and logs.
type string.
fanout.plan
Pointer at steps..outputs.plan.
type string.
fanout.workflow
Name of a workflows: sub-pipeline to run for each subtask.
type string.
gate
A human approval point.
type object.
gate.name
Name used in key paths and the dashboard.
type string.
gate.prompt
Text shown to the person deciding.
type string.
inbox
One inbox folder.
type object. required name, path.
inbox.enabled
When false, the inbox is kept but not polled.
type boolean. default true.
inbox.name
Inbox id, unique in the file.
type string. pattern ^[a-z][a-z0-9-]{0,39}$.
inbox.path
Folder polled for spec files.
type string.
loop
A bounded retry around a body.
type object.
loop.max_iterations
How many times the body may run.
type integer. default 3.
loop.name
Name used in key paths and logs.
type string.
loop.no_progress
Stop early when an iteration changes no code.
type boolean. default true.
loop.steps
Body stages. A loop cannot contain another loop.
type array. default [].
each item is loopStage.
loopStage
A stage inside a loop: a step, a parallel group, or a gate.
mcpServer
One MCP server, either a stdio command or an HTTP URL.
type object.
mcpServer.command
Stdio server argv. Mutually exclusive with url.
type array.
mcpServer.env
Environment for a command server. Each entry is {value: "..."} or {secret: true}.
type object. each entry is envEntry.
mcpServer.url
HTTP or HTTPS endpoint. Mutually exclusive with command.
type string.
orderCheck
One milestone check: a built-in or custom step that answers pass, fail, or unknown per assertion.
type object. required name.
orderCheck.assertions
Which assertions this check judges. Default all.
orderCheck.blocking
When false, results are stored but do not decide the milestone. Default true.
type boolean. default true.
orderCheck.command
Inline protocol v2 command. Must list milestone_check in its handshake features.
type array.
orderCheck.config
Free-form step config. contract-tests uses report for the JUnit XML path.
type object. extra keys allowed.
orderCheck.name
Unique check name for this factory.
type string.
orderCheck.provider
Optional model provider for an agent check.
type string.
orderCheck.services
When true, start the run's declared services first. Default false.
type boolean. default false.
orderCheck.step
Built-in contract-review or contract-tests, or a steps. command step.
type string.
orderCheck.timeout
Optional check timeout as a Go duration.
type string.
orderIntake
One order.intake entry: a built-in or configured step, or an inline command.
parallel
A fan-out group.
type object.
parallel.fail_fast
Stop the group at the first failure.
type boolean. default false.
parallel.name
Name used in key paths and logs.
type string.
parallel.steps
Step ids or step references run together.
type array. default [].
price
Token prices for one model.
type object.
price.cached_usd_per_token
Dollars per cached input token.
type number.
price.input_usd_per_token
Dollars per input token.
type number.
price.output_usd_per_token
Dollars per output token.
type number.
readinessProbe
A Work order readiness probe: the built-in test-command, a named command step, or an inline command.
repo
One labelled checkout.
type object. required path.
repo.base_branch
Branch worktrees are created from.
type string. default "main".
repo.capabilities
see repoCapabilities.
repo.command_env
see commandEnv.
repo.copy_to_worktree
Ignored folders copied from the source checkout into each new worktree before setup. Copy-on-write where the filesystem supports it. Up to 20 repo-relative paths. Use an install command that keeps existing files when you use copy_to_worktree. Some, such as npm ci, delete node_modules first.
type array.
repo.glossary
Optional glossary file. Otherwise the factory looks for GLOSSARY.md, docs/GLOSSARY.md and docs/glossary.md.
type string.
repo.path
Local checkout. Relative paths are beside kusaw.yaml.
type string.
repo.sandbox
off or required for steps whose active repos include this repo (GF-88).
type string. one of "off", "required".
repo.services
Declared processes started after setup and stopped with the worktree (GF-131). At most 8. Each has a unique name in the repo.
type array.
each item is service.
repo.setup
Commands run once in the new worktree before the pipeline. A list is all host commands. A map with host and sandbox groups runs host commands on the machine, then sandbox commands in the repo's OS sandbox. Each entry is a shell string or an object with run and an optional timeout. At most 10 per group. Timeout is a Go duration from 1s to 60m; the default is 10m. An empty map is no setup.
repo.signing
Whether factory deliveries in this repo are signed. auto (default) follows commit.gpgsign; required always signs; off never signs.
type string. one of "auto", "required", "off". default "auto".
repo.standards
Optional standards file. Otherwise the factory looks for CONTRIBUTING.md, docs/CODING_STANDARDS.md, CLAUDE.md and AGENTS.md.
type string.
repoCapabilities
Per-repo instructions, skills, and MCP servers the factory may use after approval (GF-80).
type object. extra keys allowed.
repoCapabilities.auto_approve
When true for a kind, every found item of that kind is usable without naming it.
type object.
repoCapabilities.auto_approve.instructions
Approve every discovered instruction file without listing it.
type boolean. default false.
repoCapabilities.auto_approve.mcp_servers
Approve every discovered MCP server without listing it. Warns at validate (W8).
type boolean. default false.
repoCapabilities.auto_approve.skills
Approve every discovered skill without listing it.
type boolean. default false.
repoCapabilities.instructions
Repo-relative instruction file paths allowed by name. At most 10.
type array.
repoCapabilities.mcp_env_allow
Env names or trailing-* prefixes repo MCP servers may receive (GF-28 syntax).
type array.
repoCapabilities.mcp_servers
MCP server names found in the repo's MCP config files. At most 50, matching the access name rule.
type array.
repoCapabilities.notes
Optional factory-side notes file, relative to kusaw.yaml, up to 64 KB.
type string.
repoCapabilities.skills
Skill names found under .claude/skills//. At most 50, matching the access name rule.
type array.
routingRule
One routing.rules entry. First match wins.
type object.
routingRule.match
All present keys must match.
type object.
routingRule.match.labels
Every listed label must be present on the item.
type array.
routingRule.match.repos
Every listed repo label must be present on the item.
type array.
routingRule.match.source
Exact source, or a prefix ending in *.
type string.
routingRule.match.type
Exact item type, such as bug or feature.
type string.
routingRule.workflow
Workflow to assign when the match succeeds.
type string.
sandboxEgress
Host allowlist and inject entries for network: allowlist (GF-132).
type object.
sandboxEgress.allow
Exact host names or *.suffix, optionally with :port. IP addresses and bare * are refused.
type array.
sandboxEgress.inject
Credential-holding reverse-proxy entries, or the string provider.
sandboxEgress.provider_hosts
When true (default), add each runner's declared EgressHosts.
type boolean. default true.
schedule
One cron trigger.
type object. required name, cron, spec_template.
schedule.cron
Five-field cron expression in local time.
type string.
schedule.enabled
When false, the schedule is kept but does not fire.
type boolean. default true.
schedule.name
Schedule id, unique in the file.
type string. pattern ^[a-z][a-z0-9-]{0,39}$.
schedule.spec_template
Path of the spec template queued on each fire.
type string.
scorecard
Accuracy gate then weighted speed and cost. Default weights 0.5/0.5; gate_scorers all.
type object.
scorecard.gate_scorers
Scorers that must pass the accuracy gate: all, none, or a list of names. Default all.
default "all".
scorecard.weights
Numbers from 0 to 1 that add up to 1. Default speed 0.5 and cost 0.5.
type object.
scorecard.weights.cost
Weight for cost score. Default 0.5.
type number. default 0.5.
scorecard.weights.speed
Weight for wall-time score. Default 0.5.
type number. default 0.5.
scorer
One judge. Set exactly one of criterion (built-in) or command (custom).
type object. required name, sample_rate, pass_threshold.
scorer.calibration
see calibration.
scorer.command
Argv of a custom scorer. Runs through protocol v2 with mode score. Mutually exclusive with criterion.
type array.
scorer.criterion
What the judge scores. The built-in criterion is redundant_tests. Mutually exclusive with command.
type string.
scorer.description
What a custom scorer judges, shown when labelling (the score is hidden).
type string.
scorer.env
Environment for a custom scorer. Each entry is {value: "..."} or {secret: true}. KUSAW_ names are reserved.
type object. each entry is envEntry.
scorer.name
Scorer name, unique in the file.
type string.
scorer.outcomes
Run outcomes this scorer applies to.
type array. default ["succeeded","needs_attention"].
scorer.pass_threshold
Score at or above this value passes, from 0 to 1.
type number.
scorer.sample_rate
Fraction of runs to score, greater than 0 and at most 1.
type number.
scorer.timeout
Go duration for the judge.
type string. default "5m".
service
One declared repo service started after setup (GF-131).
type object. required name, run, ready.
service.env
Extra allowlisted environment variable names (GF-28).
type array. default [].
service.name
Unique in the repo. Matches ^[a-z][a-z0-9_]{0,15}$.
type string.
service.ready
see serviceReady.
service.restart
no (default) or on-failure. on-failure restarts at most 3 times per run and waits for ready again.
type string. one of "no", "on-failure". default "no".
service.run
Shell command started through the repo's command environment. Sees KUSAW_PORT_* from the worktree's lease.
type string.
service.stop
Optional shell command to stop the service. Default: SIGTERM to the process group, SIGKILL after 10s.
type string.
service.where
sandbox or host. Unset means where the repo's steps run (in the sandbox when it is on) unless host is set (Q96).
type string. one of "sandbox", "host".
serviceReady
Exactly one of http, tcp, or log. timeout 1s to 10m, default 60s.
type object.
serviceReady.http
URL that must answer 2xx or 3xx.
type string.
serviceReady.log
Regular expression matched in the service's output.
type string.
serviceReady.tcp
Host:port or port that must accept a connection.
type string.
serviceReady.timeout
Go duration from 1s to 10m. Default 60s.
type string. default "60s".
setupEntry
One setup command: a shell string or {run, timeout}.
setupGroups
Setup commands grouped by where they run.
type object.
setupGroups.host
Commands run on the host after the worktree is ready.
see setupList.
setupGroups.sandbox
Commands run in the repo's OS sandbox after the host group. When the sandbox is off they run on the host.
see setupList.
setupList
A setup command list. At most 10 entries.
type array.
each item is setupEntry.
skill
A skill folder.
type object. required path.
skill.path
Folder containing SKILL.md, relative to kusaw.yaml or absolute.
type string.
stage
A bare step id, a step reference, or a parallel, loop, gate, fanout or candidates wrapper.
step
One step. Set builtin or command, not both.
type object.
step.args
Extra arguments after the built-in or command.
type array. default [].
step.atlas
Offer Atlas tools and overview for this step. Omitting the key uses the built-in default.
type boolean.
step.builtin
Built-in step name.
type string.
step.command
Argv of a user program. The first element must be executable.
type array.
step.command_env
Set to repo to run this custom command under the active repo's command_env.
type string.
step.completion_grace_seconds
Per-step override of worker.completion_grace_seconds. Range 5–600.
type integer. from 5 to 600.
step.config
Free-form settings for the step.
type object. default {}. extra keys allowed.
step.connector_tools
Connector tools this command step may call, as connector.tool names. Omitted on agent-backed steps means every agent_tools entry.
type array.
step.context
Connector context entries to write before this step, as connector.name (X230).
type array.
step.effects
Kinds this step may return and how they are applied (GF-92). Default: no kinds; mode apply.
type object.
step.effects.allow
Effect kinds this step may return.
type array. default [].
step.effects.mode
apply runs appliers, dry_run validates and previews, off only stores.
type string. one of "apply", "dry_run", "off". default "apply".
step.env
Environment for this step. Each entry is {value: "..."} or {secret: true}. KUSAW_ names are reserved.
type object. default {}. each entry is envEntry.
step.env_allow
Extra environment names or prefix globs for this step.
type array. default [].
step.interactive
True when the step needs a person at the terminal. Interactive steps belong in intake.
type boolean. default false.
step.max_output_retries
Extra extract calls after the first extract try for two-step structured output. 0 means one extract try. Range 0–5. Default 2.
type integer. default 2. from 0 to 5.
step.mcp
MCP servers for this step. An empty list means none. Omitting the key uses the defaults.
type array.
step.per_repo
Run the step once in each active repo. Pipeline only.
type boolean. default false.
step.prompt_args
Named arguments for prompt_file. A value is a literal string or { from, read_file, untrusted }.
type object.
step.prompt_file
Prompt template path inside the factory folder. The core renders it to the attempt's prompt.md.
type string.
step.provider
Agent provider for this step: claude-code or cursor. Omitted uses the factory default (claude-code). Intake steps always run on claude-code. Recorded on the attempt for usage, cost and metrics.
type string. one of "claude-code", "cursor".
step.retries
Retries after a failed attempt.
type integer. default 2.
step.sandbox
off or required for this step, or a mapping with mode, network, and egress (GF-88, GF-132). The most specific setting wins.
step.skills
Skills for this step. An empty list means none. Omitting the key uses the defaults.
type array.
step.timeout
Go duration, greater than 0 and at most 24h.
type string. default "10m".
stepRef
A step reference with an optional id, when clause, run line, and config overlay.
type object.
stepRef.config
Per-entry config overlay merged onto the step definition.
type object. extra keys allowed.
stepRef.id
Name used when the same step appears more than once.
type string.
stepRef.run
Shorthand for a built-in, for example kusaw step triage-group.
type string.
stepRef.step
Step id to run.
type string.
stepRef.when
Run only when steps..outputs. is set.
type string.
workflow
One named workflow: description, pipeline, optional finally and limits.
type object.
workflow.description
1 to 300 characters, shown to the classifier and in kusaw workflows.
type string.
workflow.finally
Stages that run after this workflow's pipeline.
type array.
each item is stage.
workflow.limits
Per-run time and budget overrides for this workflow.
type object.
workflow.limits.budget_tokens_per_run
Token budget for one run of this workflow.
type integer.
workflow.limits.budget_usd_per_run
USD budget for one run of this workflow.
type number.
workflow.limits.finally_budget_tokens
Token budget for this workflow's finally stages.
type integer.
workflow.limits.finally_budget_usd
USD budget for this workflow's finally stages.
type number.
workflow.limits.max_attempts
Maximum attempts in a candidates stage (2-8). Missing or 0 means 4.
type integer.
workflow.limits.run_minutes
Wall-clock minutes for one run of this workflow.
type integer.
workflow.pipeline
Stages for this workflow.
type array.
each item is stage.