Levers

The lever system is GuildHall's policy surface. Instead of scattered hardcoded defaults, every behavioral knob is a named decision point with an enumerated set of positions and full provenance.

Source: ./src/levers/Storage: ./memory/agent-settings.yamlReference: full list of levers in Levers reference.

Schema

Every lever entry has the same shape:

landing_strategy:
  position: cherry_pick_with_push
  rationale: "Land accepted work locally, then push the landing branch to origin"
  setAt: "2026-04-10T11:02:00Z"
  setBy: user-direct

• position — the actual value. Some levers are simple enums (serial, fanout_4), others are discriminated unions ({ kind: "fanout", n: 4 }).
• rationale — free text. Required; explains why this position was chosen.
• setAt — ISO 8601 timestamp.
• setBy — system-default, spec-agent-intake, user-direct, or coordinator:<name>.

Scope

There are two scopes:

• Project levers — singleton per workspace. See project levers.
• Domain levers — per coordinator domain, with a default entry as fallback. See domain levers.

Public API

import {
  makeDefaultSettings,
  readAgentSettings,
  writeAgentSettings,
  type LeverSettings,
  type ProjectLevers,
  type DomainLevers,
  type LeverSetter,
} from 'guildhall/levers'

• makeDefaultSettings() — seeds a new workspace with system defaults.
• readAgentSettings(cwd) — validated load from disk.
• writeAgentSettings(cwd, settings) — atomic write; preserves YAML comments.

Related

• Each lever has a dedicated docs page under Levers with positions, effects, and examples.
• The dashboard Settings tab exposes every lever with a ? icon that links back here.