🧹 Define a conservative layered .gitignore baseline and profile ownership

[szmyty]

Summary

Define and adopt a conservative, layered .gitignore contract for Empathy's universal repository baseline.

A recent audit reduced a 5,193-line aggregation of community ignore templates to a small high-confidence baseline. The central finding was that a universal root .gitignore should ignore machine-local clutter and unequivocally generated state, while ambiguous ecosystem names belong in the nearest project-specific .gitignore.

At the start of this issue, Empathy ignored several broad paths globally, including:

• [Bb]in/
• **/build/
• **/dist/
• **/out/
• target/
• the entire .idea/ directory
• broad credential-like extensions such as *.key
• report and coverage directories that may contain reviewed artifacts

Those patterns can silently hide legitimate source, checked-in tooling, binary fixtures, public certificates, publication outputs, or intentionally preserved evidence in a polyglot repository.

Architectural decision to encode

Use layered ownership:

1. The universal root baseline owns high-confidence operating-system debris, editor-local state, caches, logs, local environments, and universally generated dependency directories such as node_modules/.
2. Language, framework, product, publication, and repository-class profiles own ecosystem-specific outputs.
3. Ambiguous names such as bin/, build/, dist/, lib/, out/, pkg/, public/, reports/, target/, and vendor/ are not ignored universally.
4. Lockfiles and reviewed repository configuration remain tracked by default.
5. Secret protection must distinguish private local material from public certificates, examples, fixtures, and templates; broad extension patterns require explicit justification.
6. Consumer repositories may add narrower rules in the closest applicable .gitignore without weakening required baseline protections.

This issue owns the baseline contract and golden-consumer proof. Holon materialization and Pace fleet convergence remain separate downstream concerns and should receive linked follow-up issues only after this contract is accepted.

Scope

Audit and classification

• Inventory every active rule in Empathy's current root .gitignore.
• Classify each rule as:
  • universal high-confidence clutter;
  • profile-specific generated output;
  • repository-local exception;
  • security-sensitive local material;
  • dangerously broad or ambiguous;
  • obsolete or duplicate.
• Record the ownership decision for every removed or relocated rule.

Universal baseline

Create a canonical universal ignore artifact within Empathy's repository-foundation contract.

The baseline should cover, where justified:

• macOS, Windows, and Linux filesystem metadata;
• editor-local state while preserving shareable project settings;
• temporary files, logs, process state, and caches;
• local .env variants while explicitly allowing documented examples/templates;
• node_modules/ and similarly unambiguous package-manager local state;
• high-confidence Python, Dart/Flutter, JVM, CMake, Terraform, LaTeX, and test-tool caches;
• comments that explain intentional non-rules and profile ownership boundaries.

Do not copy a giant community-template aggregation into the repository.

Profile-specific rules

Move ambiguous or ecosystem-owned outputs to the relevant language, product, publication, risk, or repository-class profile.

At minimum, evaluate:

• Rust target/;
• .NET bin/ and obj/;
• generic build/, dist/, and out/;
• Go or PHP vendor/;
• publication reports/, coverage/, screenshots, snapshots, and generated documentation;
• Apple and Android binary/package outputs;
• Yarn Zero-Install state;
• certificate, key, keystore, archive, patch, and binary-fixture patterns.

A directory name is not sufficient evidence that all matching paths are disposable.

Contract integration

• Add the universal artifact and applicable overlays to foundation/catalog.json.
• Update the golden Empathy manifest to select the intended profiles.
• Preserve explicit repository-owned exceptions through the existing override contract.
• Regenerate the deterministic foundation inventory and EgoLint projection when affected.
• Document precedence between the root baseline, selectable overlays, and nested repository-local .gitignore files.
• Document how a consumer intentionally tracks a file that an overlay would otherwise ignore.

Validation

Add behavior-oriented fixtures and tests using git check-ignore --verbose or an equivalent deterministic harness.

The test matrix must prove that the baseline ignores representative local clutter while keeping legitimate source and reviewed artifacts visible.

Required visible-path cases include:

• bin/
• build/
• dist/
• Rust target/ when the Rust profile is not selected
• vendor/
• archives and patch files
• screenshots and snapshots
• VS Code project settings
• environment templates
• public certificates and binary fixtures

Required ignored-path cases include:

• node_modules/
• local .env variants
• operating-system metadata
• editor-local workspace state
• tool caches selected by the applicable profile

Also verify:

• no duplicate active rules;
• every profile-specific rule has an owner;
• catalog and manifest resolution remain deterministic;
• the checked-in golden consumer resolves without drift;
• existing repository tests and quality checks pass.

Constraints

• Preserve the existing Empathy foundation ownership model.
• Do not introduce fleet mutation into this issue.
• Do not assume an ignored path is safe to delete.
• Do not remove secret protections without replacing them with a narrower, tested rule or documented security contract.
• Do not ignore lockfiles universally.
• Do not ignore .vscode/ wholesale.
• Do not use bin/, build/, dist/, out/, target/, or vendor/ as unconditional universal rules.
• Keep the baseline readable and curated; avoid regenerating a multi-thousand-line aggregate.

Acceptance criteria

• Every current root ignore rule has a documented classification and owner.
• A canonical, conservative universal .gitignore artifact exists in the repository-foundation catalog.
• Ambiguous ecosystem outputs are removed from the universal layer.
• Required ecosystem-specific ignores are represented by selectable profiles or documented repository-local rules.
• Lockfiles remain tracked by default.
• Shareable VS Code settings remain trackable.
• Environment templates remain trackable while local environment files are ignored.
• Secret-related rules are narrow, justified, and covered by tests.
• Behavior tests prove both ignored and intentionally visible paths.
• No duplicate active rules remain in the canonical baseline.
• Foundation catalog, manifest, inventory, and generated contract validation pass.
• Empathy's complete existing validation suite passes.
• Documentation explains layered ownership, precedence, exceptions, and downstream adoption.

Definition of done

The issue is complete when Empathy provides a versioned, tested repository-baseline contract that can be consumed without silently hiding reasonable source or reviewed artifacts, with ecosystem-specific output rules owned by explicit profiles and a golden-consumer proof demonstrating the intended Git behavior.

Iteration 01 checkpoint — source and pilot accepted; shared integration next

• Accepted upstream: #85 / #86 establish the audit/baseline and validation correction; #87 establishes foundation 1.1.0 composition; #88 adopts the golden root; #90 completes the scoped foundation typing/runtime-guard cleanup. All merges are verified. fix(foundation): reconcile full-profile typing and runtime guards #89 is closed.
• Source identity: accepted Empathy b44f798bb49259f9f48416b4ffebde1103e135c0; 27 universal rules with SHA-256 79280ac4f3147ead97a0b21b01f40241238f08fa5d63abe3f81c8b64e7f179f0. Golden root remains the reviewed 80-rule selection; the migration record accounts for all 176 historical rules, 269 Git path expectations, and inherited-policy limits.
• Filament pilot: feat(foundation): adopt the pinned universal gitignore baseline filament#6 merged on 2026-09-18 as c3eb64b8087face7504e7571dc8396c19525649f; live main exactly matches the tested tree. Adopt the pinned universal gitignore baseline as the file-contract pilot filament#5 is verified complete. Its root uses only the universal baseline, no overlays/local text, with provenance, plan/byte equality, and 14 passing local behavior tests. No reusable CI or fleet-conformance claim follows from that manual pilot.
• Historical validation: fix(foundation): 🔧 resolve typing and preserve runtime guards #90's six foundation components pass their scoped typing/security checks; root suite ran 117 tests with two expected skips. Wider type/security/CI debt and inherited-policy exceptions remain explicit in fix(foundation): reconcile full-profile typing and runtime guards #89/fix(foundation): 🔧 resolve typing and preserve runtime guards #90 and the master epic. No all-green full-suite claim is made.
• Remaining acceptance owner: Reconcile inherited gitignore exceptions and prove shared consumer integration #92 now owns current nested-policy disposition and integrated consumer proof. It must reconcile the unchecked environment criterion and explicitly classify remaining full-suite findings; it does not absorb every unrelated repository defect. Canonical source corrections and reviewed exceptions require evidence, not silent edits to staged sibling copies.
• Next implementation: Materialize and safely update the accepted layered gitignore contract holon#58 provides safe materialization/adoption/update; Validate layered gitignore content, provenance, and effective Git behavior egolint#61 provides reusable semantic conformance. Reconcile inherited gitignore exceptions and prove shared consumer integration #92 consumes both for the golden/Filament proof. Shared execution stays with Validate architecture and repository structure in CI relay#5 and Run pinned EgoLint profiles through a reusable workflow relay#49; rollout is Roll out the accepted layered gitignore contract through reviewed repository waves pace#30.
• Maintainer direction: direct MegaLinter revision/bootstrap repairs remain deferred to EgoLint/Relay adoption. The accepted manual pilot proceeded under that explicit boundary. .gitattributes is selected as iteration 02 in Roadmap: solidify the universal gitattributes contract and Filament pilot #91 after the gitignore completion sequence.
• Parent/process: 🧱 [MASTER EPIC] Solidify repository file contracts, one file at a time .github#32. One bounded PR per review/merge/sync cycle; no self-merge.

Preserve #82's closure from the #88 merge. Its unchecked criteria remain honest historical gaps with named follow-up work, not completed-validation claims. Refreshed 2026-09-18 after the verified Filament merge and owner-specific roadmap reconciliation.