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
	// TrunkCollisionRenames maps a pre-rename path to its post-rename
	// path, both as observed by the ids-unique trunk-collision rule
	// (its one and only consumer, today and after G-0378): a
	// same-id-different-path pair whose paths appear here as a match
	// is the same entity moved, not a duplicate id allocation. Always
	// keyed by trunk's current path and valued by the working tree's
	// current path, regardless of which side's git history explained
	// the rename.
	//
	// Populated by two mechanisms merged into one map (ADR-0031): a
	// branch-side detector (gitops.RenamesFromRef — trailer walk + a
	// `git diff -M` content-similarity fallback, G-0109) for renames
	// the branch itself committed, and a trunk-side detector
	// (gitops.TrunkRenamesFromRef — trailer walk only, no -M fallback,
	// G-0378) for renames committed directly on trunk after the branch
	// forked. The cmd dispatcher gates both behind
	// check.DisputedTrunkIDs, an in-memory, git-free predicate: when
	// no working-tree id is disputed against trunk, neither detector
	// runs and this field stays nil.
	//
	// Tests that build trees in-memory leave it nil, in which case the
	// rule degrades to today's behavior (every different-path same-id
	// pair surfaces as a collision, modulo the archive-sweep exception).
	TrunkCollisionRenames map[string]string
	// Strays holds repo-relative file paths (forward-slash form) that
	// the loader walked under work/{epics,gaps,decisions,contracts}/
	// 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 inside those subtrees
	// linger undetected.
	//
	// Scope is the four entity-bearing subdirs, not all of work/.
	// Files at the work/ root or under non-entity sibling dirs
	// (work/migration/, work/scratch/, etc.) are outside the loader's
	// walk roots and never appear here. docs/adr/ is walked but
	// conventionally permissive (READMEs, templates, etc.), so its
	// strays are not tracked. 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
	// LocalRefIDs is the entity-id set observed across every local
	// branch ref (refs/heads/*), populated alongside TrunkIDs by the
	// cmd dispatcher (M-0212). It feeds AllocationIDs — the allocator's
	// broadened cross-branch view, which catches a sibling git
	// worktree's freshly-committed id before it collides — but NOT the
	// ids-unique check, which stays on its working-tree-vs-trunk basis
	// (E-0052 decision: the widened set is allocation-only). Tests that
	// build trees in-memory leave it nil, degrading the allocator to
	// {working-tree + trunk} behavior.
	LocalRefIDs []string
	// RemoteRefIDs is the entity-id set observed across every
	// remote-tracking ref (refs/remotes/*), populated alongside TrunkIDs
	// by the cmd dispatcher (M-0214). The remote-side mirror of
	// LocalRefIDs: it feeds AllocationIDs so an entity pushed to any
	// remote branch (a teammate's not-yet-merged work) is skipped at
	// allocation, but NOT the ids-unique check, which stays on its
	// working-tree-vs-trunk basis (G-0316). Tests that build trees
	// in-memory leave it nil.
	RemoteRefIDs []string
	// CrossBranchHits is the union of every local-branch-ref and
	// remote-tracking-ref hit (trunk.LocalRefHits ++ trunk.RemoteRefHits,
	// M-0259/AC-1), carrying kind/path/ref per hit rather than bare id
	// strings. refs-resolve and body-prose-id consult it as a second-tier
	// resolver on a local-tree miss, before firing unresolved (ADR-0030,
	// M-0259/AC-2): a hit here classifies as the non-blocking
	// cross-branch-pending subcode instead. Recomputed fresh on every
	// `aiwf check` run (no cache), so a source branch's disappearance
	// re-escalates the next reference resolution to unresolved on its own
	// (M-0259/AC-4) — nothing here needs its own escalation-tracking
	// mechanism.
	//
	// Populated alongside LocalRefIDs/RemoteRefIDs by the cmd dispatcher.
	// Tests that build trees in-memory leave it nil, degrading resolution
	// to today's two-tier (working tree, unresolved) behavior.
	CrossBranchHits []trunk.RefHit
	// CrossBranchCollisions is the canonicalized-id set for which
	// CrossBranchHits carries divergent blob content across two or more
	// refs (computed by trunk.ScanCrossBranch, M-0259/AC-3, G-0415).
	// Divergence
	// alone is ambiguous — it can mean a genuine duplicate-mint
	// collision, or just an ordinary same-entity edit still unmerged on
	// a sibling branch/worktree (D-0036) — so refs-resolve and
	// body-prose-id escalate a hit here to the distinct, visible
	// cross-branch-collision subcode instead of the ordinary
	// cross-branch-pending one, but both are non-blocking warnings; a
	// genuine duplicate mint is still caught, just later, by the
	// blocking ids-unique/trunk-collision check once both copies land
	// in a shared tree. Tests that build trees in-memory leave this
	// nil, degrading every cross-branch hit to the pending tier (the
	// pre-AC-3 default).
	CrossBranchCollisions map[string]bool
}