config

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/pocv3/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"`
}

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) 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 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 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"`
}

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.

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/pocv3/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).