Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0059: Use project-root selection with layered ignore rules

Status: accepted | Date: 2026-07-30

Tags: validation

References: RFC-0009, ADR-0009

Context

ADR-0009 selected source files through configured roots and extensions. Large repositories exposed the cost of enumerating excluded subtrees before applying exclusions, while users also needed familiar precedence and re-inclusion semantics across project defaults and governance-specific overrides. RFC-0009 defines the replacement selection contract.

Decision

Replace ADR-0009 with project-root traversal constrained by positive include patterns and layered gitignore-compatible ignore files. This direction was chosen because it applies exclusion during traversal and gives projects one established rule model for baseline and governance-specific selection.

Consequences

Positive: excluded subtrees can be pruned before enumeration, and repository conventions remain reusable. Negative: selection behavior spans configuration plus ignore files, so debugging precedence requires considering both. Replacing roots, extensions, and exclusions changes the schema and can change the selected file set; RFC-0009:C-IGNORE-MIGRATION owns that compatibility boundary. Neutral: source-reference extraction and validation remain separate from file selection.

Alternatives Considered

Walk the project root using positive include patterns and layered gitignore-compatible rules. (accepted)

  • Pros: Prunes irrelevant directories before enumeration., Reuses a familiar precedence and re-inclusion model.
  • Cons: Selection now depends on ordered ignore files in addition to configuration.

Retain configured roots and extensions while applying layered gitignore-compatible rules during traversal. (rejected)

  • Pros: Keeps explicit coarse traversal bounds and reduces configuration migration.
  • Cons: Maintains separate roots, extensions, positive selection, and ignore concepts for one file-selection decision.
  • Rejected because: Traversal-time pruning solves the performance issue, but retaining independent roots and extension axes adds configuration surface that positive path patterns already express.

Use project-root positive include patterns with a dedicated .govignore only. (rejected)

  • Pros: Keeps governance selection isolated from Git configuration.
  • Cons: Duplicates repository-wide exclusions and lets source scanning drift from established project boundaries.
  • Rejected because: Reusing .gitignore as a baseline avoids duplicating the dominant repository exclusion policy while .govignore remains an explicit override layer.