Documentation
¶
Overview ¶
Package config loads and writes the consumer repo's `aiwf.yaml`.
The file is small and deliberately so — see docs/pocv3/design/design-decisions.md §"aiwf.yaml config". The fields are:
hosts: [claude-code] # optional; PoC default and only supported value status_md: # optional; opt-out for the STATUS.md auto-update auto_update: false # default true — see StatusMdAutoUpdate
Identity is runtime-derived (per `provenance-model.md`):
- `--actor <role>/<id>` flag on the verb wins.
- else `git config user.email` → `human/<localpart>`.
- else verb refuses with a usage error.
Two legacy fields are tolerated on read for the migration window:
- `actor:` (pre-I2.5) — captured into LegacyActor; ignored for identity. Stripped on `aiwf update`. See StripLegacyActor.
- `aiwf_version:` (pre-G47) — captured into LegacyAiwfVersion; was a set-once pin that never auto-maintained itself, producing chronic doctor noise. Stripped on `aiwf update`. See StripLegacyAiwfVersion.
Validation rules:
- ActorPattern is the published regex for `<role>/<id>`; callers that resolve identity at runtime (cmd/aiwf, initrepo) consult it.
Index ¶
Constants ¶
const DefaultAllocateTrunk = "refs/remotes/origin/main"
DefaultAllocateTrunk is the trunk ref the allocator falls back to when aiwf.yaml.allocate.trunk is unset. Mirrors what `git clone` produces for a standard upstream project.
const DefaultHTMLOutDir = "site"
DefaultHTMLOutDir is the path the renderer falls back to when aiwf.yaml.html.out_dir is unset.
const FileName = "aiwf.yaml"
FileName is the canonical filename at the consumer repo root.
Variables ¶
var ActorPattern = regexp.MustCompile(`^[^\s/]+/[^\s/]+$`)
ActorPattern enforces the actor format documented in docs/pocv3/design/design-decisions.md: `<role>/<identifier>`, exactly one '/', no whitespace, neither side empty.
var ErrNotFound = errors.New("aiwf.yaml not found")
ErrNotFound reports that aiwf.yaml does not exist in the queried directory. Callers (notably resolveActor) handle this gracefully, since the file is optional pre-`aiwf init`.
Functions ¶
func StripLegacyActor ¶
StripLegacyActor removes any top-level `actor:` line from root/aiwf.yaml and rewrites the file in place. The strip is textual (line-based) rather than a YAML round-trip so user comments and key ordering survive — the legacy `actor:` key is the only field we know to be dead, and a re-marshal would regenerate the file in the marshaler's preferred shape.
Returns (false, nil) when no `actor:` line is present (file stays byte-identical), (true, nil) when one was removed, or an error when the file is unreadable / unwritable. Idempotent: callers may invoke on every `aiwf update` without churn.
`actor:` only matches at column 0 (i.e. a top-level YAML key). A nested key with an actor field name in some hypothetical future block would not be touched.
func StripLegacyAiwfVersion ¶ added in v0.5.0
StripLegacyAiwfVersion removes any top-level `aiwf_version:` line from root/aiwf.yaml and rewrites the file in place. Same shape as StripLegacyActor: textual line-based strip so user comments and key ordering survive.
Returns (false, nil) when no line is present, (true, nil) when one was removed. Idempotent — callers may invoke on every `aiwf update` without churn.
Filed under G47: the field was historically required and stamped at init time, but never auto-maintained, producing chronic doctor noise. The information is now reachable via `aiwf version` (the running binary) and `aiwf doctor --check-latest` (newer release available); the stored pin is dead weight.
Types ¶
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 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"`
}
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 ¶
Load reads aiwf.yaml from root. Returns ErrNotFound when the file is absent so callers can distinguish "missing config" (acceptable pre-init) from "malformed config" (always an error).
func (*Config) AllocateTrunkRef ¶
AllocateTrunkRef returns the configured trunk ref (or the default) and whether the value was explicitly set in aiwf.yaml. The "explicit" bit drives the missing-ref policy: an explicitly-named ref that doesn't resolve is a hard error; an unconfigured default that doesn't resolve falls back to working-tree-only when the repo also has no remotes.
func (*Config) HTMLOutDir ¶
HTMLOutDir returns the configured output directory or the default when unset. Callers should resolve to an absolute path against the repo root before passing to the renderer.
func (*Config) StatusMdAutoUpdate ¶
StatusMdAutoUpdate returns whether the consumer wants the pre-commit hook installed and `STATUS.md` regenerated on every commit. Default true: the framework's opt-out, not opt-in. The committed `STATUS.md` is the user's content once tracked; flipping the flag controls whether the *hook* is installed, not whether the file is deleted.
func (*Config) Validate ¶
Validate enforces the documented constraints. Called by Load and expected to be called by Write before serialization.
Identity (the actor field) is no longer stored — it's runtime- derived per `provenance-model.md`. Any incoming `actor:` key is captured by LegacyActor for the deprecation note in `aiwf doctor`, but is not validated here (a malformed legacy value is harmless since runtime resolution doesn't consult it).
`aiwf_version:` is no longer required (G47). Pre-G47 yamls still load fine; the legacy value is captured into LegacyAiwfVersion and stripped on `aiwf update` via StripLegacyAiwfVersion.
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 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"`
}
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.
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.
Source Files