Policies, presets and authority levels

Each team has one policy: what kanman may touch, how much it may spend, when a human must approve, and which choices it may make alone.

The policy is how a team sets the rules for kanman. It answers four questions: what may kanman touch, how much may it spend, when must a person approve, and which choices may it make on its own. Every check against the policy is logged, so you can always see why kanman did or did not do something.

Each team has exactly one policy. Open it under Settings > Policy on the team. Only workspace admins can change it, and every change is recorded in the audit log as policy_changed with a new policy version. Each run remembers the policy version it started with.

What the policy covers

Area Settings Default
Scope allowed_repos, denied_paths, max_changed_files, max_changed_lines preset paths, 30 files, 800 lines
Executor and models executor, fallback_executor, routing, billing_mode Claude Code, pass-through
Budgets budget_run_cents, budget_day_cents, budget_month_cents 2.00 EUR per run
Approvals plan_approval, plan_approval_min_size, merge_policy, auto_merge_max_lines, authority_overrides plan approval always, a person merges
Time and load working_hours, max_concurrency always, 1 at a time
Secrets secret_names none
Gate require_acceptance_spec, rework_attempts, gate_failure_budget spec required (except Trial), 1 rework, 3 failures
Personality intake_scope, maintenance, cadence set by the preset

The policy settings reference lists every setting with its values.

Secrets are listed by name only. Their values stay in your CI settings or vault and never pass through kanman.

Presets

You do not have to set every knob. Five presets bundle them by intent:

Preset For Concurrency Who files work Maintenance Acceptance spec required Default denied paths
Trial The first pilot week, repositories without specs 1 humans only off no infra/**, **/*.tf, .github/workflows/**
Focused kanman only works on what people filed 1 humans only off yes same as Trial
Balanced Most teams, the recommended default 2 humans and kanman off yes same as Trial
Autonomous Teams that let kanman file and pick up more work 4 humans and kanman off yes .github/workflows/**
Hardening Teams that want steady maintenance work 2 humans and kanman on, 2 per day yes same as Trial

Presets only change the “personality” knobs: concurrency, who may file work, maintenance and cadence, plus the default denied paths and, for Trial, the spec requirement. Safety does not depend on the preset: the sandbox, the outcome gate, the diff guard and the clean-room check are the same for everyone.

When you edit any knob a preset controls, the badge changes to Custom (based on Balanced), so it is always clear that you diverged from the preset.

You pick the preset when you set up a team (the setup suggests Balanced) and can switch it at any time under Settings > Policy.

Choose and tune a preset helps you pick.

Authority levels

Every choice kanman makes is classified by a fixed table, in code, not by asking a model. There are three levels:

Level What kanman does Kinds of choices
AUTO Acts silently. Visible in the audit log write_ac (write acceptance criteria), set_priority_in_band, link_duplicate, resequence, nudge_run
NOTIFY Acts and records a notice close_duplicate, split_story, pause_thrashing_run
ESCALATE Stops and asks in the decision inbox, with a recommendation and 2 to 4 options expand_scope, change_security_posture, touch_production_data, overspend, contradict_operator, touch_denied_path, plan_approval, merge

Three rules keep this predictable:

  1. Unknown kinds default to NOTIFY. kanman never acts silently on something the table does not know.
  2. Risk can only raise the level. An irreversible action, a high blast radius or a cost of 20.00 EUR or more is always ESCALATE. A medium blast radius or a cost of 5.00 EUR or more is at least NOTIFY.
  3. Teams can only raise. With authority_overrides (When kanman acts on its own under Settings > Policy, Advanced) you can move a kind up, for example split_story from NOTIFY to ESCALATE. You can never move one down.

Plan approval and merging take their base level from the approval settings, see Policy settings.

Coming in a later release

kanman taking the AUTO and NOTIFY actions on its own (linking and closing duplicates, splitting stories, reordering the backlog, nudging or pausing a run) and posting one-line notices about them arrive in a later release. Today the table decides when kanman stops and asks: plan approval, merging, denied paths, repositories, change size and budget.

The safety floor

Some things no policy can change:

  • touch_production_data, change_security_posture and overspend are always ESCALATE.
  • .kanman/acceptance/** is always denied to executors, on top of your own denied paths.
  • The sandbox, the diff guard and the clean-room check are on for every preset.

An override that would lower a level has no effect: the stricter level always wins.

Every check is logged

Each policy check writes a policy_decision entry to the audit log with its result (allowed or denied), so you can answer “why did kanman stop here?” and “who allowed this?” months later. Executors can also ask before they try: the check_policy MCP tool answers “may I touch infra/?” without starting anything.

Last updated: January 1, 0001

Open kanman