tree

type LoadError struct {
	Path string
	Err  error
}

type Tree struct {
	// Root is the absolute path to the consumer repo root the tree was
	// loaded from.
	Root string
	// Entities holds every successfully-parsed entity. Order is the
	// order encountered during the directory walk, which is stable
	// across runs but not otherwise specified.
	Entities []*entity.Entity
	// Stubs holds entities whose source file failed to parse. Each
	// carries only id (derived from the path), kind, and path; body
	// fields are zero. Stubs are deliberately not in Entities so that
	// frontmatter-shape, status-valid, and similar body-level checks
	// don't emit spurious findings. They exist so reference resolution
	// can still locate a target by id, preventing one file's parse
	// failure from cascading into "unresolved reference" findings on
	// every entity that links to it. The original parse failure is
	// reported as a load-error finding.
	Stubs []*entity.Entity
	// PlannedFiles records repo-relative file paths (forward-slash form)
	// that a verb plans to write but hasn't yet. Used by checks that
	// otherwise consult disk so that validate-then-write verbs can
	// validate the projected world, including files about to be created.
	// Loaded trees leave this nil.
	PlannedFiles map[string]struct{}
	// ReverseRefs maps each entity id (and each composite id mentioned
	// as a reference target) to the ids of entities that reference it.
	// Built from entity.ForwardRefs at Load time; consumed by aiwf show's
	// referenced_by field, by aiwf check audits ("ADR is unreferenced"),
	// and by the I2.5 provenance scope-reachability check.
	//
	// Composite-id targets roll up to their parent: a gap with
	// `addressed_by: M-007/AC-1` appears in the AC's referrer list AND
	// in M-007's referrer list. Each value-slice is sorted ascending
	// and de-duplicated for stable output.
	ReverseRefs map[string][]string
	// TrunkIDs is the entity-id set observed in the configured trunk
	// ref's tree, used by AllocateID (so a new id can't collide with
	// trunk) and by the ids-unique check (so a working-tree id that
	// also exists at a different path on trunk surfaces as a finding
	// before push).
	//
	// Tree.Load does not populate this field — the cmd dispatcher reads
	// the trunk via the trunk package once per verb run and assigns
	// here so the verb's projection check sees the same trunk view.
	// Tests that build trees in-memory leave TrunkIDs nil, in which
	// case the allocator and the check rule degrade to working-tree-
	// only behavior (the previous default).
	TrunkIDs []trunk.ID
	// TrunkRef is the resolved trunk ref name (e.g.
	// "refs/remotes/origin/main") or empty when no trunk read
	// happened. The reallocate tiebreaker uses it as the second
	// argument to `git merge-base --is-ancestor` when two entities
	// collide on an id and the verb has to pick which side to
	// renumber. Populated alongside TrunkIDs by the cmd dispatcher;
	// empty in tests that don't set it (the verb falls back to
	// today's "ambiguous, pass a path" error in that case).
	TrunkRef string
	// Strays holds repo-relative file paths (forward-slash form) that
	// the loader walked under work/* but could not classify as a
	// recognized entity file via entity.PathKind. The tree-discipline
	// check (G40) reports each as `unexpected-tree-file`; without that
	// field the loader's silent skip would let any LLM-written stray
	// linger under work/ undetected.
	//
	// Strays are tracked only under work/*; docs/adr/ is conventionally
	// permissive (READMEs, templates, etc.) and is left alone. Files
	// inside a contract's directory (work/contracts/C-NNN-*/) are
	// recorded here but filtered by the check rule, since contracts
	// legitimately carry schema/fixture artifacts alongside contract.md.
	Strays []string
}