Harness Field Reference

This is a living document. It is the authoritative reference for harness field classifications, merge rules, and the ForgeConfig struct. Update this document whenever you add a new field to Harness or ForgeConfig, move a field between classification tiers, or change merge semantics.

The architectural decisions behind these rules are recorded in ADR-0045 (forge-portable schema) and ADR-0088 (CEL-guarded overlays). Those ADRs are point-in-time records; this document reflects the current state.

Field classification

Harness fields are classified into two tiers based on whether they can be overridden inside forge.<platform> blocks or overlays: entries.

Fields that can appear at both levels

These fields can appear at the harness top level (as defaults) and inside ForgeConfig (forge blocks or overlay entries):

Field	Rationale
pre_script	Scripts often call forge-specific CLIs (gh, glab)
post_script	Push, PR/MR creation is forge-specific
skills	Some skills wrap forge-specific APIs
runner_env	Token names and event URLs differ per forge
validation_loop	Validation scripts may call forge-specific tools
policy	Sandbox policies may need forge-specific filesystem or process rules; network access is managed via providers (ADR-0065) but non-network policy sections can still differ per forge
providers	Providers may need forge-specific entries (e.g., different API endpoints per platform); concatenated (top-level + forge)
openshell	OpenShell profiles may need forge-specific configuration; profiles concatenated (top-level + forge)
host_files	Host files may need forge-specific entries (e.g., different credential files per platform); deduplicated by dest path (child wins)
env	Env config (runner and sandbox sub-maps) may need forge-specific entries (e.g., different token names per forge); sub-maps merged independently, forge/child keys win (ADR-0055)

Fields that stay at top level only

These fields are platform-neutral and cannot be overridden per-forge or per-overlay:

Field	Rationale
agent	Agent definitions are forge-agnostic
model	Model selection is independent of forge
image	Container images are platform-neutral
api_servers	REST proxies abstract forge details
plugins	Plugin directories are forge-agnostic; each entry is a local path or a pinned URL and keeps its own env/pi options (ADR-0038, ADR-0094). Top level only — not a ForgeConfig field, so it is not settable under forge: or overlays: (a plugins: key there is ignored, not an error)
agent_input	Agent prompt input is forge-agnostic
timeout_minutes	Timeouts are operational, not forge-specific
sandbox_timeout_seconds	Sandbox-level timeout, not forge-specific
security	Security scanning is forge-agnostic
allowed_remote_resources	URL allowlist for resource fetching (ADR 0038)
description	Documentation, no runtime effect
role	Agent identity is forge-agnostic
slug	Kept top-level; per-forge slug differences handled via base composition
base	Composition is a structural concern, not forge-specific
doc	Documentation path, no runtime effect
effort	Effort level is operational, not forge-specific
readonly_repo	Repo access mode is forge-agnostic
allow_runtime_fetch	Runtime fetch opt-in is forge-agnostic
max_runtime_fetches	Fetch cap is operational, not forge-specific
trigger	CEL trigger expression is evaluated against normalized events, not forge-specific (ADR-0061)

Merge and inheritance rules

When a forge block or overlay is merged into the harness top level, each field type follows specific merge semantics. The same rules apply during base: composition (base → child merging).

Two independent precedence axes govern field resolution (see #6798):

• Specificity (within a layer): Conditional forge/overlay values override same-layer top-level values.
• Derivation (across layers): Child-layer values override inherited base-layer values. Each base layer's forge and overlay blocks are resolved into top-level fields before merging into the child, so inherited conditional values cannot override the child's explicit settings.

Field type	Merge behavior	Nil vs empty
Scalar fields	Forge/child value overrides top-level/base value	Absent = inherit from top level / base
skills	Merged with deduplication by basename (forge/child overrides top-level/base)	Absent (nil) = inherit; skills: [] = empty list merged with base (base entries are returned)
runner_env	Top-level/base map merged with forge/child map; forge/child keys win	Absent (nil) = inherit; runner_env: {} = no forge-specific keys (top-level env still inherited)
validation_loop	Forge/child value replaces top-level/base value entirely	Absent (nil) = inherit from top level / base; explicit empty struct = intended to mean "no validation" (see ADR-0045 open questions)
providers	Concatenated (top-level/base + forge/child)	Absent (nil) = inherit; providers: [] = no forge-specific additions (top-level providers still apply)
openshell	profiles concatenated (top-level/base + forge/child)	Absent (nil) = inherit; empty profiles: [] = no forge-specific additions
host_files	Concatenated (base + child); deduplicated by dest path (child wins)	Absent (nil) = inherit
plugins	Concatenated (base + child)	Absent (nil) = inherit
api_servers	Concatenated (base + child)	Absent (nil) = inherit
env	Sub-maps (runner, sandbox) merged independently; forge/child keys win (ADR-0055)	Absent (nil) = inherit
security	Child replaces base entirely (if non-nil)	Absent (nil) = inherit
overlays	Concatenated (base + child); all matching entries merged at resolution with later precedence (ADR-0088)	Absent (nil) = inherit

ForgeConfig struct

ForgeConfig is the shared field payload used by both legacy forge: platform blocks and current overlays: entries (via OverlayEntry's yaml:",inline" embedding). The type name is a legacy artifact from the original forge feature (ADR-0045); it was retained when ADR-0088 introduced overlays to avoid a rename-heavy migration. Both mechanisms use mergeForgeConfig to apply their fields onto harness top-level values.

// ForgeConfig holds platform-specific harness configuration.
// This is purely declarative YAML config — it selects which
// scripts, skills, host files, and env vars to use per platform. It is
// distinct from the forge.Client interface (internal/forge/),
// which is the runtime abstraction for forge API operations.
type ForgeConfig struct {
    PreScript      string            `yaml:"pre_script,omitempty"`
    PostScript     string            `yaml:"post_script,omitempty"`
    Policy         string            `yaml:"policy,omitempty"`
    Skills         []SkillEntry      `yaml:"skills,omitempty"`
    Providers      []string          `yaml:"providers,omitempty"`
    OpenShell      *OpenShellConfig  `yaml:"openshell,omitempty"`
    HostFiles      []HostFile        `yaml:"host_files,omitempty"`
    ValidationLoop *ValidationLoop   `yaml:"validation_loop,omitempty"`
    RunnerEnv      map[string]string `yaml:"runner_env,omitempty"`
    Env            *EnvConfig        `yaml:"env,omitempty"`
}

Current resolution pipeline

The current forge resolution pipeline is:

Unmarshal → validateForge → ResolveForge(platform) → Validate

Overlay resolution (ADR-0088)

overlays: is the successor to deprecated forge: blocks. Each overlay entry has a when: CEL expression and the same override fields as ForgeConfig. All entries whose when evaluates to true are merged in order, with later matches taking precedence over earlier matches.

Resolution pipeline

Unmarshal → validateForge → validateOverlays →
ResolveForge(platform) → ResolveOverlays(event, forgePlatform, config) → Validate

When event is nil (CLI flows without event context, such as fullsend lock or fullsend run when no event can be recovered), ResolveOverlays substitutes an empty map so overlays conditioned on runtime.forge or config can still evaluate and match. Overlays that reference event fields should use has() to guard field access (e.g., has(event.source) && event.source.system == "jira").

CEL environment

Overlay when expressions are evaluated with:

Variable	Type	Source
event	normevent.Event	The triggering event — fields like source.system, entity.kind, transition.kind
runtime.forge	string	Effective forge platform (precedence: CLI flag > config.forge > CI env vars)
config	map[string]any	Full per-repo config from config.yaml

Mutual exclusion

forge: and overlays: must not coexist in the same harness (post-merge). forge: is deprecated; new harnesses should use overlays: instead.

Related

• ADR-0045: Forge-portable harness schema — original architectural decision (Superseded by ADR-0088)
• ADR-0088: CEL-guarded overlays — current overlay mechanism
• Harness Composition: Merge function checklist (step 6 references this document)
• Issue #5579: Harness field integration pipeline (complementary checklist)