check

func BodyProseIDIndex ¶ added in v0.12.0

func BodyProseIDIndex(t *tree.Tree) BodyProseIndex

BodyProseIDIndex builds the id-resolution index that ScanBodyProseID consumes from the tree's entities, stubs, and trunk-id set.

Exposed so verbs that scan planned-write body content at verb time (G-0184 verb-time scan) share the index with the tree-walking bodyProseID rule. Verbs should build the index once before the loop over planned files, then pass it to ScanBodyProseID per file.

func BuildCommitDAG ¶ added in v0.21.0

func BuildCommitDAG(ctx context.Context, root string) (*CommitDAG, error)

BuildCommitDAG runs one `git rev-list --all --reflog --parents` and parses it into a SHA→parents map. The `--reflog` flag is load-bearing: the orphaned-AI-commit walk asks about commits that were force-pushed away and are no longer reachable from any ref, so a plain `--all` DAG would omit exactly the commits the walk inspects (`--all` is a superset of what the oracle's first-parent index needs, so the one DAG serves both). Returns an error only on a genuine git failure; callers treat that as "cannot determine ancestry / first-parent" and fall back to their per-call git path, matching the prior behavior.

func AreaCoverage ¶ added in v0.18.0

func AreaCoverage(t *tree.Tree, areas []AreaPaths, coverageRoots []string) []Finding

AreaCoverage (warning) reports any immediate child directory of an operator-declared coverage root that is claimed by no declared area's `paths:` glob — an unslotted project (E-0044, M-0185). It is the *covering* law of the area↔directory partition: where AreaDeadGlob asserts no area column is empty and AreaOverlap asserts no directory row is claimed twice, coverage asserts every in-scope directory is claimed by some area. The monorepo-specific catch for a newly-added project that nobody slotted.

The universe is scoped and opt-in: the operator names the coverage root(s) (aiwf.yaml: areas.coverage_roots), and only the immediate child directories of those roots must tile. Directories outside any declared root are unscoped and never flagged, so the single-project / semantic-section repo — which declares no coverage root — is never flagged wholesale. The model is deliberately not total-partition: the filesystem remainder (README, docs/, top-level config) is legitimately uncovered.

Activation and the opted-in-but-undeliverable diagnostics:

• no coverage root declared — fully inert; the knob's presence is the activation signal, so absence means the law does not apply (M-0185/AC-4);
• coverage root declared but no area declares any `paths:` — the path oracle is dormant, so instead of silently doing nothing the check emits one area-coverage-no-paths finding: the operator opted in but the prerequisite is missing (M-0185/AC-8);
• a declared root that resolves to no directory (does not exist, or names a file) emits area-coverage-root-missing — dead config, the coverage analogue of area-dead-glob; a silently-skipped dead root would give false confidence that coverage is active (M-0185/AC-8).

Enumeration is single-level (one os.ReadDir per declared root) and reads the filesystem read-only; a transient/permission IO error yields no findings rather than failing (the roadmapCaseCollision precedent). Dot-prefixed immediate children (.git / .github / .claude / …) are skipped — hidden directories are tooling / VCS artifacts, never projects (the Unix dotfile convention), and .claude is materialized by aiwf itself, so flagging them would be a never-actionable false positive. The skip covers only HIDDEN dirs: a "." root still enumerates non-hidden top-level dirs (docs/, work/, node_modules/), so point coverage at a dedicated project-parent root (projects/, apps/) rather than "." unless every non-hidden top-level dir is genuinely a project. The "is this directory claimed?" test routes through the areamatch SSOT (M-0180/AC-1), the same matcher the path-axis checks use — no second matcher.

Composed at the CLI layer (internal/cli/check) with the declared areas and coverage roots sourced from config — the same seam AreaDeadGlob and AreaOverlap use — so the pure check.Run stays config-agnostic. Severity is warning, escalated to error under areas.required by ApplyAreaRequiredStrict.

func AreaDeadGlob ¶ added in v0.18.0

func AreaDeadGlob(t *tree.Tree, areas []AreaPaths) []Finding

AreaDeadGlob (warning) reports any declared area path glob that matches no real file or directory under the repo root — dead config: a renamed, deleted, or typo'd project path leaving that area's path oracle empty. The check is per-glob: each declared glob must locate at least one path, and each dead glob fires its own finding naming the area and the glob.

Reads the filesystem read-only through the area-glob matcher (areamatch, the SSOT introduced in M-0180/AC-1) and never fails on IO: an empty or unreadable root, or a glob that errors during the walk, is silently skipped (the roadmapCaseCollision precedent). Malformed globs are owned by config-load validation (Tier 1), not re-reported here.

Composed at the CLI layer (internal/cli/check) with the declared areas sourced from config — the same seam AreaUnknown uses — so the pure check.Run stays config-agnostic. Inert when no area declares a `paths:` glob (label-only / legacy string-form config), so a paths-less areas block fires nothing on the path axis (M-0180/AC-5). Severity is warning, escalated to error under areas.required by ApplyAreaRequiredStrict.

func AreaMistag ¶ added in v0.18.0

func AreaMistag(t *tree.Tree, areas []AreaPaths, touchedByEntity map[string]map[string]bool, ackedMistags map[string]bool) []Finding

AreaMistag (warning) reports an entity whose linked commits' work landed in a DIFFERENT area's path territory than the one the entity is tagged to. It is the path-vs-tag consistency check: with `paths:` (M-0179) declared and the entity ↔ commit linkage aiwf records via the `aiwf-entity:` trailer (gathered by GatherEntityPaths), the touched-files-vs-glob comparison catches "filed against the wrong area, flew under the radar" — the failure label-only areas are blind to.

The entity's effective area comes from t.ResolvedArea (so a milestone is judged against its parent epic's area), matched against the declared globs via the areamatch SSOT. Several guards make the rule inert where it can't speak:

• no area declares `paths:` → nothing to check against;
• the entity is untagged, or carries the reserved `global` sentinel (inherently cross-cutting, ADR-0021) → skipped;
• the entity's own area declares no `paths:` → can't locate "inside";
• the entity has no linked commits / no touched paths → nothing to judge;
• archived entities are out of scope (ADR-0004 §"check shape rules").

Severity is warning and NEVER escalates — unlike dead-glob / overlap, it is deliberately absent from ApplyAreaRequiredStrict, because legitimate cross-cutting work exists and the acknowledge path (M-0181/AC-6) is the sanctioned escape valve, not a strictness bump. Composed at the CLI layer with the gathered paths and declared areas, like the other path-axis rules.

ackedMistags is the set of canonical entity ids that have a sovereign `aiwf acknowledge mistag` commit in history (gathered by WalkAcknowledgedMistags, M-0181/AC-6); those entities are exempted — the operator has affirmed the cross-cutting work is intentional. A nil set exempts nothing.

func AreaOverlap ¶ added in v0.18.0

func AreaOverlap(t *tree.Tree, areas []AreaPaths) []Finding

AreaOverlap (warning) reports any directory claimed by more than one declared area — ambiguous attribution: two areas whose `paths:` globs both match a common path. The ambiguity would make the entity-touching checks (mistag M-0181, auto-derive M-0182) behave non-deterministically there, so the path oracle must be a partition (each directory claimed by at most one area). One finding per overlapping area-pair, naming both areas and a representative shared path.

Reads the filesystem read-only through the area-glob matcher (areamatch, M-0180/AC-1) and never fails on IO: an empty or unreadable root, or a glob that errors during the walk, is silently skipped (the roadmapCaseCollision precedent). Malformed globs are owned by config-load validation (Tier 1, areamatch.Validate), not re-reported here.

Composed at the CLI layer (internal/cli/check) with the declared areas sourced from config — the same seam AreaUnknown and AreaDeadGlob use — so the pure check.Run stays config-agnostic. Inert with fewer than two areas carrying paths. Severity is warning, escalated to error under areas.required by ApplyAreaRequiredStrict.

func AreaRequired ¶ added in v0.18.0

func AreaRequired(t *tree.Tree, declared []string, required bool) []Finding

AreaRequired (error) reports any non-archived entity of a self-tagging root kind (epic, ADR, gap, decision, contract) whose `area` frontmatter is empty, when the consumer has opted into strictness via `aiwf.yaml: areas.required: true` (M-0178). It is the present-at-all chokepoint for the 1:1 monorepo where every entity belongs to exactly one project — orthogonal to AreaUnknown, which polices present-⇒-declared.

The knob is the gate: with required false the rule emits nothing (no warning→error bump — it simply does not fire). The remediation is `aiwf set-area <id> <member>` (M-0183).

Three guards, in order:

• Inert when required is false OR declared is empty (no `areas` block). The empty-declared guard is defensive — config.Load rejects required:true with zero members, so it is unreachable through the normal path, but the rule stays self-contained.
• Milestone skip (load-bearing): a milestone's `area` is blanked at load and derived from its parent epic (tree.go, E-0043 / M-0171/AC-3), so an untagged milestone always reads area=="". Skipping KindMilestone is what makes an untagged epic fire exactly once rather than once per untagged milestone underneath it.
• Archive scoping (ADR-0004 §"check shape rules"): archived entities are out of scope for active linting, matching the other shape-and-health rules.

Composed at the CLI layer (internal/cli/check) with the declared set and the required bool sourced from config — the same seam AreaUnknown uses — so the pure check.Run stays config-agnostic.

func AreaUnknown ¶ added in v0.17.0

func AreaUnknown(t *tree.Tree, declared []string) []Finding

AreaUnknown (warning) reports any non-archived entity whose `area` frontmatter value is present and non-empty but not a member of the declared set (`aiwf.yaml: areas.members`). It is the present-⇒-declared chokepoint for E-0043 — typo protection for the optional grouping tag, the authoritative surface a creation-time flag alone can't cover (a hand-edit or an `aiwf import` can introduce an undeclared area without passing through `aiwf add --area`).

Three behaviors fall out of the guards, in order:

• Inert when declared is empty (no `areas` block): present `area` values parse but nothing validates, per M-0171's "the field is inert until a block is declared" contract.
• Absence (empty `area`) is never evaluated: absent / explicit-null / empty all deserialize to "" and only a present, non-empty value can be "unknown".
• Archive scoping (ADR-0004 §"check shape rules"): archived entities are out of scope for active linting, matching the other shape-and-health rules.

The rule reads the *stored* area, so only root kinds that carry their own `area` can fire; a milestone (area blanked at load, derived from its parent epic) never double-reports under a bad-area epic.

Composed at the CLI layer (internal/cli/check) with the declared set sourced from config — the same seam TreeDiscipline, the contract checks, and the tests-metrics check use — so the pure check.Run stays config-agnostic (the boundary M-0171/AC-4's metamorphic guard pins). Severity is warning with no strictness knob (E-0043 / M-0172 decision).

func FSMHistoryConsistent ¶ added in v0.9.0

func FSMHistoryConsistent(ctx context.Context, root string, t *tree.Tree, ackedSHAs map[string]bool, head []HeadCommit) []Finding

FSMHistoryConsistent is the kernel chokepoint that makes the per- entity status FSM a tree-invariant rather than just a verb- precondition (closes G-0132 when all of M-0130 lands). The rule walks every entity's commit history in DAG order, observes every status-change commit, and — once AC-2/3/4 land the per-subcode predicates — emits findings per violation.

M-0130 lands the rule incrementally:

• AC-1 (this file): walker scaffolding. walkStatusChanges enumerates status-change observations across every entity in the tree via DAG-aware per-parent comparison. FSMHistoryConsistent returns no findings yet — the per-subcode predicates land in AC-2/3/4. The walker's correctness (per-parent comparison, rename tracking via --follow, single-commit and no-change short-circuits, multi-entity independence, branched-history phantom-transition avoidance) is pinned by the test suite in fsm_history_consistent_test.go.
• AC-2: illegal-transition subcode — observation's (Prior, Next) is outside entity.AllowedTransitions and Trailers lacks aiwf-force.
• AC-3: forced-untrailered subcode — sovereign-act-shape transition (per entity.IsSovereignActShape) without aiwf-force trailer.
• AC-4: manual-edit subcode — catch-all: legal-in-FSM AND not sovereign-act-shape AND no aiwf-verb trailer. Includes audit- only suppression.
• AC-5: hint table entries + SKILL.md rows (already landed).
• AC-6: audit catalog update (legal-workflows-audit.md).

The rule is wired in internal/cli/check/check.go's Run() alongside RunProvenanceCheck, NOT in this package's Run(). The per-entity git-walk is too expensive for the per-commit pre-commit hook's policy-test path; pre-push and explicit `aiwf check` invocations get the full audit.

Walker design contract (the load-bearing correctness pin for AC-1):

The walker is DAG-aware, not linearization-aware. For each commit C that touched an entity's file, the walker compares C's status against the status at each of C's actual git parents (not against the linearization-neighbor commit in `git log --follow` output). The original AC-1 design walked linearization adjacency, which silently produced phantom transitions across branch boundaries — e.g., a retitle commit on a feature branch with status=proposed followed in `git log` order by a promote-to-active on a parallel branch would emit an "active → proposed" observation that corresponds to no real edit. Per-parent comparison eliminates the phantom by structurally restricting comparisons to actual parent- child edges in the DAG.

M-0159/AC-3: ackedSHAs is the gather-layer-computed map of retroactively-acknowledged commit SHAs (per WalkAcknowledgedSHAs in acks.go). The rule consumes it directly rather than recomputing internally — the CLI gather layer computes it once per check invocation and passes the result to all three rules that consume it. A nil/empty map is "no acknowledgments" (the rule polices normally).

func Run ¶

func Run(t *tree.Tree, loadErrs []tree.LoadError) []Finding

Run executes every check against the tree and returns all findings, ordered first by severity (errors first), then by code, then by path. Per-file load errors from the tree loader are surfaced as load-error findings ahead of the regular checks.

Run also fills in Line (1-based) and Hint on every finding. Line is derived from the field name the check annotated; Hint is looked up from a Code+Subcode → hint table.

func RunIDRenameUntrailered ¶ added in v0.12.0

func RunIDRenameUntrailered(renames []UntrailedIDRename, ackedSHAs map[string]bool) []Finding

RunIDRenameUntrailered emits one warning finding per record in renames, minus those whose SHA appears in ackedSHAs.

The rule is pure: the gather layer (WalkUntrailedIDRenames) does all git work and filtering; the rule itself just maps records to findings. Same shape as the M-0159/AC-3 ack-helper-lift pattern: `ackedSHAs map[string]bool` carries the set of commits retroactively acknowledged via `aiwf acknowledge illegal`; per- SHA closed-set scoping; nil or empty map is "no acknowledgments."

Each record produces its own finding (no per-entity aggregation, mirrors M-0106/AC-10's per-commit firing). The finding's Path is the new (post-rename) path so the operator's editor can jump to the file that needs aiwf-reallocate retroactively; EntityID is the new id when known.

func RunIsolationEscape ¶ added in v0.12.0

func RunIsolationEscape(commits []scope.Commit, oracle BranchOracle, cherryPicked, ackedSHAs map[string]bool) []Finding

RunIsolationEscape applies the M-0106 branch-choreography rule against a commit history. The rule scans commits for those carrying both aiwf-actor: ai/... and aiwf-entity: <id> trailers, finds each candidate's active scope at the commit's time, and fires isolation-escape when the commit's branch does not match the scope's recorded aiwf-branch:.

commits must be ordered oldest-first (matching the RunProvenance convention). oracle supplies per-commit branch info; a nil oracle is treated as "no branch info available" and the rule returns silently — a graceful degradation for environments where the gather layer cannot determine commit branches (e.g., a bare repo fragment in a test fixture without ref history).

cherryPicked is the set of commit SHAs the gather layer identified as `git cherry-pick -x` re-authors of upstream commits: both (a) the commit body carries the `(cherry picked from commit <sha>)` marker line that `git cherry-pick -x` writes by default AND (b) the commit's git committer email differs from its git author email (the identity gap that `git cherry-pick` produces by default when a different identity re-authors the original — committer becomes the current user, author preserved from source). When a commit's SHA is in this set the rule treats it as a sovereign human re-author (corner case 8 / AC-6) and suppresses any isolation-escape finding against it; the audit trail lives in the committer-vs-author identity gap and the marker itself. A nil/empty map means "no cherry-pick info available"; the rule then polices as usual (no false negatives — only known-cherry-picks are suppressed).

The both-signals contract is the gather-side's per-commit derivation, implemented by check.WalkCherryPicks in internal/check/cherry_picks.go (M-0159/AC-6 / G-0202). Either signal alone is insufficient: a fabricated marker (no real cherry-pick) lacks the gap; an amended commit (gap without -x) lacks the marker. Real-git E2E coverage lives in internal/cli/integration/branch_scenarios_ac6_test.go.

Per-commit firing: each violating commit produces its own finding. No aggregation, no per-entity summary — the user wants the cardinality so each escaped commit is individually addressable (AC-10).

Algorithm (per commit, in chronological order):

1. Skip if the commit is not an AI commit on an entity (must carry both aiwf-actor: ai/... and aiwf-entity: <id>).
2. Find the most recent opened-scope commit on the same entity in the preceding commits. If none, skip (AC-9 — no scope, no policing). Cycle 3 will further filter on the scope's current state (paused → silent per AC-5).
3. Read the scope's aiwf-branch: trailer. If absent — legacy pre-M-0102 scope — skip (non-retroactive per epic §"Out of scope").
4. Ask the oracle for the commit's branch set. If empty — "unknown branch" — skip (do not fire on commits the kernel cannot confidently classify).
5. If the bound branch is in the commit's branch set, silent (AC-4 — commit rides bound branch).
6. Otherwise fire isolation-escape with the commit's SHA, the entity id, the bound branch, and the actual branch list as evidence.

M-0159/AC-3: ackedSHAs carries the set of commit SHAs that have been retroactively acknowledged via `aiwf acknowledge illegal`. The CLI gather layer computes the map once per check invocation (via WalkAcknowledgedSHAs in acks.go) and passes it to all three rules that consume it; rule-internal recompute is forbidden. A commit whose SHA appears in ackedSHAs is exempted from this rule's finding even when it would otherwise fire (same per-SHA closed-set scoping the M-0136/AC-2 illegal-transition exemption uses). Nil or empty map means "no acknowledgments" and the rule polices as usual.

func RunOrphanedAICommits ¶ added in v0.12.0

func RunOrphanedAICommits(orphans []OrphanedAICommit, ackedSHAs map[string]bool) []Finding

RunOrphanedAICommits emits one CodeIsolationEscapeOrphanedAICommit warning per orphaned AI-actor commit, honoring per-SHA acks.

orphans is the typed gather output from WalkOrphanedAICommits. ackedSHAs is the M-0159/AC-3 acknowledgment set; an entry in the map exempts that SHA from this rule the same way it exempts isolation-escape, id-rename-untrailered, etc.

Per-SHA dedup: an orphan that surfaced on multiple branches (uncommon; would require the commit to have been the tip on more than one branch over time) fires once. The first (branch, date) pair seen names the finding.

func RunPromoteOnWrongBranch ¶ added in v0.12.0

func RunPromoteOnWrongBranch(commits []scope.Commit, expectedBranches map[string]string, dag *CommitDAG, branchTips map[string]string, trunkShort string, ackedSHAs map[string]bool, t *tree.Tree) []Finding

RunPromoteOnWrongBranch applies the AC-8 rule to a commit history. expectedBranches maps entity ids to the expected parent-branch short name; empty/missing values silence the rule for that entity (fail-shut on correctness).

commits must be ordered oldest-first (matches the RunProvenance convention). Unlike the original M-0161/AC-8 design, this rule no longer asks a BranchOracle "what branches is this commit reachable from" — that question requires enumerating and name-filtering local branches, which is exactly what silently missed G-0270's incident (the activation commit landed on a non-ritual-shaped branch, so the oracle's branch enumeration never indexed it, and the rule stayed silent on an "unknown branch"). Instead it asks the narrower, branch-name-independent question "is this commit correctly reachable from the expected branch," via dag, branchTips, and trunkShort. Only a nil dag fail-shuts the whole rule (no ancestry data at all to test against).

The correctness test is NOT a single ancestor check — plain full-ancestry (any path) can't distinguish two very different milestone histories once the epic's ritual branch has been merged and deleted (its normal end-of-life, per aiwfx-wrap-epic): a milestone activation commit correctly made on that branch becomes, after the merge, a full ancestor of trunk's tip too — arriving via the merge commit's non-first parent, never itself on trunk's own lineage. A milestone activation that instead skipped the ritual branch and landed directly on trunk is ALSO a full ancestor of trunk's tip, but IS on trunk's own first-parent chain. The same fixture-verified pattern occurs for epics too (aiwfx-wrap-epic's own "promote E-NN active" step, run from the epic's own branch just before it is merged and deleted — confirmed against this repo's own history). One check handles both kinds uniformly:

• Correct if the commit is an ancestor of expected's own tip (branchTips[expected]) — for an epic this already IS trunk's tip (expected == trunkShort), so this alone covers both "made directly on trunk" and "made on a branch since merged into trunk"; for a milestone this covers the still-live, in-flight epic branch.
• Otherwise, for a milestone whose epic branch has since been merged and deleted (absent from branchTips), still correct if the commit is an ancestor of trunk's tip while NOT itself on trunk's own first-parent chain — i.e. it arrived via a merge, not by landing directly on trunk (which would mean the milestone skipped its epic branch entirely).

dag is the shared in-memory commit DAG (check.BuildCommitDAG), built once per check invocation. branchTips maps a branch's short name (as expectedBranches' values name them — the configured trunk short name for epics, "epic/<slug>" for milestones) to that branch's current LOCAL tip SHA; an absent entry (the branch doesn't exist locally — never cut, or cut and since deleted) is not ambiguous on its own — see the two-step check above for how it resolves. Comparing against the local branch (not a remote-tracking ref) is deliberate: a legitimate, correct, not-yet-pushed activation commit is an ancestor of local trunk immediately, but would not yet be an ancestor of a remote-tracking ref. trunkShort is the configured trunk short name, used to resolve trunk's own tip from branchTips independently of expected (which for a milestone names the epic branch, not trunk).

ackedSHAs honors M-0159/AC-3 acknowledgments via the shared per-SHA exemption.

t is the current entity tree, consulted to resolve a commit's aiwf-entity: trailer forward through any reallocation before the expectedBranches lookup (G-0308). expectedBranches is keyed by the *current* tree's ids; a commit that predates a reallocate carries the freed id verbatim in its trailer, and that id may since have been reclaimed by an unrelated entity. Resolving the trailer id through the rename chain (in-window aiwf-prior-entity: trailers) and then prior_ids frontmatter (out-of-window reallocations) — the same two-step RunProvenance uses for authorization-out-of-scope — finds the expectation for the commit's *actual* entity instead of the id's current claimant. A nil t skips only the prior_ids fallback; in-window rename-chain resolution (walkRenameChain) still applies since it reads solely from commits.

func RunProvenance ¶

func RunProvenance(commits []scope.Commit, t *tree.Tree) []Finding

RunProvenance returns provenance findings for the given commit history. commits must be ordered oldest-first (`git log --reverse`) and should already be filtered to those carrying any `aiwf-*` trailer; pre-aiwf commits are silently skipped by the per-rule checks anyway, but pre-filtering keeps the work proportional.

t is the current entity tree, consulted by the authorization-out-of-scope rule for reference reachability.

The function is pure (no I/O, no git subprocess); the caller (cmd/aiwf) gathers commits via gitops and hands them in.

func RunTrailerVerbUnknown ¶ added in v0.10.0

func RunTrailerVerbUnknown(commits []scope.Commit, registeredVerbs, ritualVerbs map[string]struct{}, ackedSHAs, postCutoffSHAs map[string]bool) []Finding

RunTrailerVerbUnknown returns one finding per commit in commits whose `aiwf-verb:` trailer value is neither in registeredVerbs (the kernel Cobra command tree) nor in ritualVerbs (the non-kernel verbs stamped by embedded ritual skills). Commits without an `aiwf-verb:` trailer, with an empty value, or whose value resolves to either closed set are silent.

An empty registeredVerbs set short-circuits to no findings — the verb enumeration runs at RunE time and could in principle return empty (cobra tree wiring failure); we'd rather skip than flood every commit as "unknown."

Per G-0190 the caller is expected to derive ritualVerbs from the embedded ritual snapshot (typically via skills.RitualTrailerVerbs) so the allowlist stays in lock-step with what the rituals actually stamp. A nil ritualVerbs is treated as the empty set; the kernel `add`/`promote`/etc. verbs still resolve via registeredVerbs.

M-0159/AC-3: ackedSHAs carries the set of commit SHAs that have been retroactively acknowledged via `aiwf acknowledge illegal`. The CLI gather layer computes the map once per check invocation (via WalkAcknowledgedSHAs in acks.go) and passes it here so historical stray commits with `aiwf-verb: <fabricated>` trailers can be quieted without rewriting history. Per-SHA closed-set scoping; nil or empty map is "no acknowledgments." Ack is checked before the cutoff decision so an explicit acknowledgment overrides every severity transition.

G-0218 Patch 2: postCutoffSHAs carries the set of commit SHAs that descend from HookInstallSHA (computed once per check invocation by the CLI gather layer via `git rev-list HookInstallSHA..HEAD`). Findings on these commits emit at SeverityError with a remediation hint — the commit-msg hook would have refused them at composition time, so a post-cutoff fabricated trailer means the commit bypassed the hook (`--no-verify` or git plumbing). Pre-cutoff commits (SHA absent from the map) stay at SeverityWarning per the G-0150 baseline so existing trunk history isn't retroactively broken. nil or empty postCutoffSHAs degrades to "all warning" — the safe fallback for shallow clones, forks that diverged before the hook landed, or any future state where the cutoff SHA is unreachable from HEAD.

Closes G-0150; G-0218 Patch 2 tightens severity for post-cutoff.

func RunUntrailedAudit ¶

func RunUntrailedAudit(commits []UntrailedCommit, ackedSHAEntities map[string]map[string]bool) []Finding

RunUntrailedAudit returns `provenance-untrailered-entity-commit` findings — one per (commit, entity) pair — for every untrailered commit in the supplied slice that touched an entity file. The caller is expected to scope `commits` to the unpushed range (typically `@{u}..HEAD`) so already-pushed pre-aiwf history is silently ignored.

One finding per entity, not per commit: a manual commit that touches three entity files emits three findings, each tagged with the entity id. This is what makes per-entity audit-only suppression work — `aiwf <verb> M-001 --audit-only` clears the M-001 finding without affecting the others on the same commit. Each finding's message names exactly one entity, which keeps individual lines short even when commits touch many entity files (matters for squash, merge, and bulk-import commits).

The finding is an ERROR (G-0231 item 3, bumped from WARNING after the merge-commit carveout cleared the historical noise and the remaining direct-edit findings were SHA-verified-acked via `aiwf acknowledge illegal --for-entity`).

Two coverage mechanisms suppress findings:

1. audit-only — when a later commit in the same range carries `aiwf-audit-only:` and its `aiwf-entity:` matches the entity id, the finding for that (commit, entity) pair is suppressed. Composite ids on audit-only commits roll up to the parent milestone for matching, mirroring how composite ids on manual commits resolve to the parent file. Per-entity blanket — clears ALL prior untrailered findings for the entity. Operator-attested reason; no SHA binding. Intended for entity status flips that bypassed `aiwf promote`.

2. acknowledge-illegal --for-entity (G-0231 item 3) — when an ack commit carries BOTH `aiwf-force-for: <sha>` AND `aiwf-entity: <id>` trailers, the finding for that exact (sha, id) pair is suppressed. Per-(SHA, entity) precision; the verb verifies at WRITE time that <sha>'s diff actually touches <id>'s file (kernel walks git diff-tree; operator-attested bindings are refused without mechanical evidence). Intended for historical body edits where the SHA is real but the kernel should still be able to verify the binding.

Mechanism 2 is the tighter mechanism. The audit-only path remains for the per-entity blanket case (status flips); the acknowledge-illegal path is the SHA-verified case (body edits).

Defensive fallback: if a commit touched paths that PathKind recognizes but IDFromPath cannot parse to an id (a bug in the path scheme would be the only realistic cause), one path-tagged finding fires per such path. EntityID is empty in that branch.

func ScanBodyProseID ¶ added in v0.12.0

func ScanBodyProseID(body []byte, entityID, path string, idx BodyProseIndex) []Finding

ScanBodyProseID classifies every id-shaped token in body (the bytes after the YAML frontmatter delimiter) and returns one finding per unique (token, subcode) pair, deduped within this body. Path and entityID are used only to populate the Finding's locator fields — the scanner is otherwise stateless, so it can run against on-disk content (the tree-walking bodyProseID rule) or against planned- write bytes that don't yet exist on disk (verb-time pre-flight).

Non-prose content is masked (not stripped) via proseMask before scanning, so byte offsets in the input remain stable across the masking step. Finding.Line is set to the 1-based line number within body where the matched token starts; callers that want file-relative Line (the bodyProseID tree-walk rule) add the body's start-of-file line offset themselves.

The idx parameter is the resolution index from BodyProseIDIndex; callers that scan multiple bodies should build it once and reuse.

func ScanSkillBodyID ¶ added in v0.21.0

func ScanSkillBodyID(body []byte, path string) []Finding

ScanSkillBodyID classifies every id-shaped token in the given content (a whole shipped *.md file, frontmatter included, or a bare body) and returns one finding per unique real-id token, deduped within this content. A token fires only when it matches a kind's strict, digit-bearing id pattern (bare or composite); canonical letter-N placeholders and malformed shapes are not this rule's concern (placeholder normalization is policed separately).

Non-prose content is masked (not stripped) via proseMask before scanning, so byte offsets stay stable and tokens inside code constructs or non-prose link carriers are exempt by construction. Finding.Line is 1-based within the given content; when the caller passes the whole file (skillBodyIDReference does), that line is already file-relative.

Path populates the finding locator only; the scanner is otherwise stateless, so it runs against on-disk content (skillBodyIDReference) or against literal test bytes.

func TreeDiscipline ¶

func TreeDiscipline(t *tree.Tree, allow []string, strict bool) []Finding

TreeDiscipline reports any file under work/{epics,gaps,decisions, contracts}/ that the loader walked but could not classify as a recognized entity file. This is the G40 mechanical guarantee for the entity-bearing subtrees: the LLM must not write directly inside them — tree-shape changes go through verbs, body-prose edits stay inside existing entity files, and stray hand-written files in those subtrees are flagged at validation time.

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, never registered as strays, and never flagged here. The threat model is the LLM mistaking the entity tree as a scratch space, not the operator parking a transient file alongside it.

Filtering, in order:

1. Files inside a recognized contract's directory (work/contracts/C-NNN-<slug>/) are auto-exempt — contracts legitimately carry schema/fixture artifacts alongside contract.md, and the binding lives in aiwf.yaml.
2. Files matching any pattern in `allow` (filepath.Match, forward-slash, repo-relative) are exempt. Consumers configure these via `aiwf.yaml: tree.allow_paths`.
3. Everything else surfaces as a finding.

Severity is warning by default. When `strict` is true (consumer opts in via `aiwf.yaml: tree.strict: true`), the severity is promoted to error so the pre-push hook blocks the push.

Run does *not* call this — it lives outside the standard rule chain so render/status callers don't get tree-discipline noise on every read. `runCheck` invokes it at the validation chokepoint.

func WalkHeadCommits ¶ added in v0.21.0

func WalkHeadCommits(ctx context.Context, root string) ([]HeadCommit, error)

WalkHeadCommits walks HEAD's reachable history once, oldest-first, and returns one HeadCommit per commit. Oldest-first matches the `--reverse` order readProvenanceCommits depends on; the map-building consumers (acks, audit-only, cherry-picks) are order-insensitive.

Returns (nil, nil) for an empty root, a non-git directory, or a repo with no commits yet — the consumers treat a nil slice as "no commits / no exemptions".

Fail-loud contract (M-0216 Finding 1): a catastrophic `git log HEAD` failure — a repo whose HEAD resolves (so hasGitCommits is true) but whose reachable history cannot be read, e.g. a corrupt object store or a partial/blobless clone missing a reachable commit — returns a non-nil error. The sole production caller (internal/cli/check) fails the whole check with ExitInternal on that error rather than reading the unreadable history as "no commits". This restores the fail-loud behavior the pre-refactor readProvenanceCommits had: a shared walk that silently returned nil here would disable the provenance / isolation-escape / promote-on-wrong-branch integrity checks on a degraded repo with no signal at all. The error path is outside the byte-identical claim's domain — a healthy tree never triggers it.

One `git log --reverse HEAD` subprocess replaces the five the gather rules used to each spawn (E-0053 / M-0216 AC-5).

func WalkOrphanedAICommits ¶ added in v0.12.0

func WalkOrphanedAICommits(ctx context.Context, root string, dag *CommitDAG, trunkShort string) []OrphanedAICommit

WalkOrphanedAICommits walks the reflog of every ritual branch under refs/heads/, identifies non-fast-forward updates (the previous tip was not an ancestor of the new tip — the canonical force-push shape), reads trailers from each orphaned tip, and returns one OrphanedAICommit per orphan that carries aiwf-actor: ai/... + aiwf-entity: <id>.

Algorithm (per ritual ref):

1. `git reflog show <ref> --pretty=format:%H %gd` lists the reflog entries newest-first.
2. Walk consecutive pairs (newer, older). older was the ref's tip BEFORE the update that landed at newer.
3. If older is NOT an ancestor of newer (`git merge-base --is-ancestor older newer` exits non-zero), the update was a non-fast-forward and older was orphaned.
4. Read older's trailers via `git log -1 --pretty=%B older`. If aiwf-actor starts with "ai/" AND aiwf-entity is non-empty, surface the orphan.

Returns nil on non-git directories, empty repos, and repos with no ritual refs. Reflog absence (e.g. core.logAllRefUpdates =false) is handled at the oracle layer (M-0161/AC-3 typed- error contract emits OracleErr with Capability "reflog- disabled" → isolation-escape-oracle-failure advisory); this walker simply finds no entries to inspect.

Per-SHA deduplication: an orphan that appears across multiple ref reflogs (rare; would require the orphan tip to have been the tip on multiple refs at different times) surfaces once per (SHA, Branch) pair; the rule consumer deduplicates by SHA when emitting findings.

func WalkUntrailedIDRenames ¶ added in v0.12.0

func WalkUntrailedIDRenames(ctx context.Context, root, ref string) []UntrailedIDRename

WalkUntrailedIDRenames walks merge-base(HEAD, ref)..HEAD for commits that rename id-bearing entity files WITHOUT an aiwf-verb trailer in the rename-class closed set. Returns one record per qualifying rename; multiple renames in one commit produce multiple records. Closes the gather-side seam for AC-4.

Returns nil for all error conditions — ref empty, ref unresolved, no commits on HEAD, no common ancestor, transient git subprocess failure. Matches WalkCherryPicks's "benign fail-shut" precedent at internal/check/cherry_picks.go: the rule degrades to "no records" rather than blocking `aiwf check` on a git hiccup, since the chokepoint is one rule among many and a transient git failure should surface other findings rather than aborting the pass.

Performance: one `git log` to enumerate the range with trailers, then one `git show -M --diff-filter=R` per untrailered commit to extract renames. Same shape as gitops.renamesFromAiwfVerbTrailers at the gather layer; for kernel-tree-sized branches the cost is well under a second.