config

type Agent ¶ added in v0.24.0

type Agent struct {
	Model  string `yaml:"model,omitempty"`
	Effort string `yaml:"effort,omitempty"`
}

Agent configures the model tier and reasoning effort a single shipped role agent's card is materialized with (G-0353). Both fields are optional: an omitted field is left off the card frontmatter, so that agent inherits the session default. The map key on Config.Agents is the shipped agent's name (e.g. "reviewer"); an unrecognized name is ignored at materialization time (initrepo reports it), not rejected here — config cannot enumerate the shipped agent set without importing skills (a layering inversion).

This is advisory, never load-bearing: a guarantee must not depend on which tier ran. Validation therefore only checks that a *set* value is in the closed vocabulary; it does not police model×effort compatibility (that is the operator's experiment, and the compatible set shifts as models change).

type Allocate ¶

type Allocate struct {
	Trunk string `yaml:"trunk,omitempty"`
}

Allocate carries the consumer's id-allocator configuration. Trunk names the git ref the trunk-aware allocator unions into its view of existing ids; an empty value means "use the default trunk ref" and AllocateTrunkRef returns DefaultAllocateTrunk in that case.

See docs/design/id-allocation.md for the full model.

type Archive ¶ added in v0.8.0

type Archive struct {
	SweepThreshold *int `yaml:"sweep_threshold,omitempty"`
}

Archive carries the consumer's drift-control configuration for the per-kind archive convention (ADR-0004). SweepThreshold is a tristate via *int: nil means "not specified, take the default (no threshold — `archive-sweep-pending` stays advisory)", &N is an explicit hard threshold past which the aggregate finding escalates from warning to error. Mirrors the StatusMd.AutoUpdate tristate so "unset" is always distinguishable from a meaningful zero. Use the getter Config.ArchiveSweepThreshold rather than reading the pointer directly so callers don't have to repeat the default.

Default behavior (empty Archive block, or absent archive.sweep_threshold): `archive-sweep-pending` stays advisory regardless of count. Teams choose their own discipline; the kernel does not nag.

type Areas ¶ added in v0.17.0

type Areas struct {
	Members []Member `yaml:"members,omitempty"`
	Default string   `yaml:"default,omitempty"`
	// Required (M-0178) opts the 1:1 monorepo into strictness: when true,
	// an untagged entity of a self-tagging root kind is a blocking
	// `area-required` (error) finding. Default false (absent) leaves the
	// pre-knob (E-0043) behavior byte-for-byte unchanged. validate()
	// rejects required:true with zero members (an unsatisfiable "every
	// entity must be a member of the empty set").
	Required bool `yaml:"required,omitempty"`
	// CoverageRoots (M-0185) opts the multi-project monorepo into the
	// scoped-coverage law: each listed directory's immediate child
	// directories are projects expected to be claimed by some area's
	// `paths:` glob, and an unclaimed child raises area-unslotted. Its
	// presence is the activation signal — absent, the coverage check is
	// inert, so the single-project / semantic-section repo is never
	// flagged wholesale. Each root is a repo-relative directory path
	// ('/'-separated, no leading slash, no `..` segments); roots may be
	// nested and several may be declared for a mixed-depth layout (the
	// immediate-children contract is per declared root). Adding it means
	// adding `coverage_roots` to knownAreasKeys, or the areas-block
	// strict-key guard rejects it as unknown on read.
	CoverageRoots []string `yaml:"coverage_roots,omitempty"`
}

Areas declares the closed set of workstream area tags (E-0043, E-0044). Members is the closed member set the optional `area` frontmatter field validates against (label + optional location). Default is a DISPLAY LABEL ONLY for the untagged complement in grouped views — never a member of the tag set, never written to an entity. An empty block (no members) leaves the `area` field inert.

Members accepts a backward-compatible dual form (E-0044, M-0179): a bare string (`- app-a`, the legacy E-0043 shape) or a `name`/`paths` mapping (`- {name: app-a, paths: [projects/app-a/**]}`). Name-consuming readers go through MemberNames(), the derived single source of truth for the member label set.

func (a Areas) MemberNames() []string

func (a *Areas) UnmarshalYAML(value *yaml.Node) error

type Config ¶

type Config struct {
	LegacyAiwfVersion string           `yaml:"aiwf_version,omitempty"`
	LegacyActor       string           `yaml:"actor,omitempty"`
	Hosts             []string         `yaml:"hosts,omitempty"`
	StatusMd          StatusMd         `yaml:"status_md,omitempty"`
	TDD               TDD              `yaml:"tdd,omitempty"`
	HTML              HTML             `yaml:"html,omitempty"`
	Allocate          Allocate         `yaml:"allocate,omitempty"`
	Tree              Tree             `yaml:"tree,omitempty"`
	Archive           Archive          `yaml:"archive,omitempty"`
	Entities          Entities         `yaml:"entities,omitempty"`
	Guidance          Guidance         `yaml:"guidance,omitempty"`
	Areas             Areas            `yaml:"areas,omitempty"`
	Worktree          Worktree         `yaml:"worktree,omitempty"`
	Logging           Logging          `yaml:"logging,omitempty"`
	Agents            map[string]Agent `yaml:"agents,omitempty"`
	Hooks             map[string]Hook  `yaml:"hooks,omitempty"`
}

Config is the in-memory shape of aiwf.yaml. Hosts is omitted when the on-disk file leaves it absent (which is the typical case).

StatusMd is the opt-out surface for the pre-commit hook that keeps `STATUS.md` in sync with the entity tree. Default behavior (block absent, or block present with `auto_update` absent) is on; an explicit `auto_update: false` opts out. See StatusMdAutoUpdate.

LegacyActor captures any pre-I2.5 `actor:` key still present in the on-disk file. The value is ignored for identity resolution (which is runtime-derived); the field exists so `aiwf doctor` can surface a deprecation note pointing the user at `git config user.email`.

func Load(root string) (*Config, error)

func (c *Config) AllocateTrunkRef() (ref string, explicit bool)

func (c *Config) ArchiveSweepThreshold() (n int, set bool)

func (c *Config) EntityTitleMaxLength() int

func (c *Config) HTMLOutDir() string

func (c *Config) HookDecision(name string) (enabled, decided bool)

func (c *Config) StatusMdAutoUpdate() bool

func (c *Config) TrunkBranchShortName() string

refs/remotes/<remote>/<name>  →  <name>
refs/heads/<name>             →  <name>

func (c *Config) Validate() error

func (c *Config) WireClaudeMd() bool

func (c *Config) WorktreeDir() string

type Entities ¶ added in v0.8.0

type Entities struct {
	TitleMaxLength *int `yaml:"title_max_length,omitempty"`
}

Entities carries the consumer's policy for entity-shape constraints the kernel applies when writing new entity files. TitleMaxLength caps the length of `--title` accepted by mutating verbs that write titles (`aiwf add`, `aiwf retitle`, `aiwf import`) and the length of `<new-slug>` accepted by `aiwf rename`. Title and slug share the same budget so on-disk filenames and frontmatter titles stay in sync — every kernel render surface (CLI tables, HTML render, git-log subjects, `aiwf history`, filesystem) degrades uniformly rather than diverging.

Default behavior (empty Entities block, or absent entities.title_max_length): the cap is DefaultEntityTitleMaxLength (80 chars — the Conventional Commits subject-line convention). Consumers who want longer or shorter caps override here per G-0102.

type Guidance ¶ added in v0.14.0

type Guidance struct {
	WireClaudeMd *bool `yaml:"wire_claudemd,omitempty"`
}

Guidance carries the consumer's opt-out for aiwf maintaining its per-turn LLM guidance import in the repo-root `CLAUDE.md` (ADR-0018). WireClaudeMd is a tristate via *bool mirroring StatusMd.AutoUpdate: nil → default (true), &false → explicit opt-out, &true → explicit opt-in. Use the getter Config.WireClaudeMd, not the pointer.

Default behavior (empty Guidance block, or absent guidance.wire_claudemd): aiwf wires and self-heals the marker-wrapped `@.claude/aiwf-guidance.md` import on every `aiwf init` / `aiwf update` — the framework's opt-out, not opt-in. There is deliberately no CLI flag; the wiring is automatic, like skill/hook materialization.

type HTML ¶

type HTML struct {
	OutDir       string `yaml:"out_dir,omitempty"`
	CommitOutput bool   `yaml:"commit_output,omitempty"`
}

HTML holds the consumer's settings for the static-site render produced by `aiwf render --format=html`. OutDir is the directory the renderer writes into (relative to the repo root unless given as an absolute path); CommitOutput records the consumer's intent to commit the rendered files. The gitignore block managed by `aiwf init` / `aiwf update` is *derived* from CommitOutput — the consumer expresses intent here, and the framework reconciles the gitignore on the next admin verb run.

Default OutDir: "site" — the standard SSG convention. Default CommitOutput: false — gitignore the output and publish via CI.

type Hook ¶ added in v0.26.0

type Hook struct {
	Enabled *bool `yaml:"enabled,omitempty"`
}

Hook configures whether a single materialized Claude Code hook aiwf ships is enabled in this repo (ADR-0032). Enabled is a tristate via *bool, mirroring StatusMd.AutoUpdate/Guidance.WireClaudeMd: nil means "no decision recorded yet — undecided," &false is an explicit decline, &true is an explicit consent. Unlike those two (whose nil means "take the default"), a Hook's nil has no default to fall back to — it must gate through the consent prompt (`aiwf init`/`aiwf update`) rather than being resolved silently one way or the other.

The map key on Config.Hooks is the shipped hook's name, mirroring Config.Agents: an unrecognized name is not rejected here — config cannot enumerate the shipped hook set without importing skills (a layering inversion) — it is reported at materialization time instead. Use the getter Config.HookDecision rather than reading the pointer directly.

type Logging ¶ added in v0.27.0

type Logging struct {
	Level       string `yaml:"level,omitempty"`
	Format      string `yaml:"format,omitempty"`
	Destination string `yaml:"destination,omitempty"`
}

Logging carries the consumer's diagnostic-logging configuration (ADR-0017). All three fields are optional and independently overridable by the matching AIWF_LOG/AIWF_LOG_FORMAT/AIWF_LOG_FILE env var (env beats yaml beats default, per field). This block only carries the raw, already-parsed strings; internal/logger owns the slog-domain validation (closed level/format sets) and the precedence resolution over them.

A separate type here (rather than this field's type being logger.YAMLConfig directly) isn't a layering restriction — config importing logger is a legal downward edge (config is tier 6, logger is tier 7; areamatch, also tier 7, is already imported here). It's schema.go's reflection walker: isStructContainer and its siblings detect a nested block by testing whether the field's rendered type name has a "config." prefix, so a field typed logger.YAMLConfig would render as a flat leaf instead of the nested logging.level / logging.format / logging.destination structure GenerateExample() needs. Use Logging.ToYAMLConfig() to convert at a call site rather than re-declaring the field-by-field copy.

func (l Logging) ToYAMLConfig() logger.YAMLConfig

type Member ¶ added in v0.18.0

type Member struct {
	Name  string   `yaml:"name"`
	Paths []string `yaml:"paths,omitempty"`
}

Member is a single declared workstream area (E-0044, M-0179): a Name (the tag entities carry in their `area:` frontmatter) and an optional Paths list locating the area's source in a monorepo. Paths are validated as well-formed strings only at this layer — glob matching against them is deferred to M-0180, where the first match call site lives. A member declared in the legacy string form (`members: [app-a]`) decodes with Name set and Paths nil.

Adding a field here means adding its key to knownMemberKeys, or the strict-key guard (G-0287) rejects it as unknown on read. There is no parallel writer struct to keep in lockstep: the areas-block writer no longer reconstructs members — `aiwf rename-area` surgically rewrites only the renamed name token (M-0195) — so a new sibling key or field is preserved through a rename automatically rather than being silently dropped.

type SchemaField ¶ added in v0.25.0

type SchemaField struct {
	// Path is the dotted key path as it appears (or would appear) in
	// aiwf.yaml, e.g. "tdd.strict". A slice-of-struct field's elements use a
	// "[]" path segment (e.g. "areas.members[].name"); a map-of-struct
	// field's elements use "<key>" as a placeholder for the dynamic map key
	// (e.g. "agents.<key>.model").
	Path string
	// Type is the field's Go type rendered for display (e.g. "bool",
	// "[]string", "config.TDD" for a nested block).
	Type string
	// Description is a one-line, consumer-facing summary of the field,
	// looked up from fieldDescriptions by Path. Empty when the path has no
	// registry entry — a state the anti-drift test in schema_test.go treats
	// as a failure for every path Schema() actually returns.
	Description string
}

SchemaField describes one yaml-tagged field in the aiwf.yaml schema, contributed by walking the Config struct tree via reflection (E-0057).

func Schema() []SchemaField

type StatusMd ¶

type StatusMd struct {
	AutoUpdate *bool `yaml:"auto_update,omitempty"`
}

StatusMd carries the opt-out for the pre-commit hook that regenerates `STATUS.md`. AutoUpdate is a tristate via *bool: nil means "not specified, take the default (true)", &false is an explicit opt-out, &true is an explicit opt-in. Use the getter Config.StatusMdAutoUpdate rather than reading the pointer directly so callers don't have to repeat the default.

type TDD ¶

type TDD struct {
	RequireTestMetrics bool     `yaml:"require_test_metrics,omitempty"`
	Strict             bool     `yaml:"strict,omitempty"`
	TestPaths          []string `yaml:"test_paths,omitempty"`
}

TDD carries opt-in governance for the TDD model. RequireTestMetrics gates the `acs-tdd-tests-missing` warning emitted by `aiwf check`: when true, every AC at `tdd_phase: done` under a `tdd: required` milestone must have at least one commit in its history carrying an `aiwf-tests:` trailer or the check warns. Default false — the trailer is informational metadata; consumers who want stricter governance opt in at the project level.

Strict promotes a defined set of TDD-related findings from warning to error so the pre-push hook blocks the push. The bumper covers `entity-body-empty` (M-066/AC-2) and `milestone-tdd-undeclared` (G-0268). Single source of truth for the project's TDD strictness posture — no parallel field, no second config knob. Default false. See check.ApplyTDDStrict for the precise set of codes covered.

TestPaths lists the globs that classify a repo-relative path as a test path for the red/green diff-shape gate on `--phase` promotes (M-0276); entries reuse the areamatch glob SSOT and are Tier-1 validated at load.

type Tree ¶

type Tree struct {
	AllowPaths []string `yaml:"allow_paths,omitempty"`
	Strict     bool     `yaml:"strict,omitempty"`
}

Tree is the consumer's policy for what may live under `work/`. AllowPaths is a list of repo-relative glob patterns (filepath.Match semantics) that exempt files from the tree-discipline check — useful for project-specific scratch dirs or templates the consumer genuinely wants alongside the entity tree. Strict promotes the `unexpected-tree-file` finding from a warning to an error so the pre-push hook blocks the push.

Default behavior (empty Tree block): contract artifact dirs are auto-exempt; everything else under work/ is reported as a warning. See docs/design/tree-discipline.md.

type Worktree ¶ added in v0.18.0

type Worktree struct {
	Dir string `yaml:"dir,omitempty"`
}

Worktree carries the consumer's default placement for the git worktrees the start rituals (`aiwfx-start-epic` / `aiwfx-start-milestone`) create. Dir is a single repo-relative directory; the kernel default is DefaultWorktreeDir. See ADR-0023 and E-0046 for why in-repo placement is the default (a sandboxed devcontainer session can only root in a worktree under the mounted workspace).