Roadmap: solidify the universal gitattributes contract and Filament pilot

[szmyty]

Outcome

Make .gitattributes the second file-contract iteration after .gitignore, using the same bounded PR/review/merge process and Filament as the first consumer.

Provide a curated universal baseline that avoids cross-platform text and binary handling surprises, with explicit profile/repository exceptions and real Git evidence. Build from the existing work.

Parent/process: egohygiene/.github#32.

Verified starting point

At Empathy 98778e8442d3be3ea7a3d1f62b71f33969346ecc:

• A substantial root .gitattributes already declares automatic text detection/LF, Windows command exceptions, source/lockfile handling, binary extensions, diff choices, and GitHub Linguist metadata.
• foundation/catalog.json already requires the gitattributes artifact, with description “Git text, EOL, binary, and generated-file behavior.” It has no attribute-content markers or layered source registry.
• Filament's accepted gitignore pilot is merged; Filament has no attributes file at the inspected merge.

This issue must audit and strengthen the existing contract rather than treating an empty or copied file as complete.

Scheduling and dependencies

Selected by the maintainer; queued after the gitignore completion sequence in the master epic. This is an explicit work-order preference, not a claim that attributes semantics technically depend on every ignore rollout task.

Do not start implementation until the current .gitignore iteration has its agreed completion/deferred boundaries reconciled.

The current ordered queue is egohygiene/holon#58 → egohygiene/egolint#61 → #92 → shared execution through egohygiene/relay#5 / egohygiene/relay#49 → reviewed adoption in egohygiene/pace#30. The master epic records actual readiness and any explicitly deferred stages; this issue is the next selected file after that closeout. Preserve the existing decision to defer direct MegaLinter repairs. A future decision to overlap independent work should be explicit.

Roadmap — one bounded PR at a time

Part 1: audit and specify

• Inspect live instructions, architecture, decisions, existing attributes/editor configuration, nested attributes, file types, CI, and open PRs.
• Classify every current rule as universal, profile-specific, repository-specific, redundant, or needing evidence.
• Record purpose, applicability, canonical source/version, ownership, local variation, migration/update behavior, and verification.
• Audit choices that can hide useful review evidence or misclassify text: for example the current *.drawio binary, notebook/minified-file diff suppression, forced-text extension lists, and broad documentation/Linguist rules.
• Use Git's attributes reference as the semantic authority and primary vendor documentation for optional integrations.

Deliver the reviewable rule decisions and behavioral fixtures before bulk migration.

Part 2: canonical baseline and contract integration

• Define the smallest evidence-backed universal text/EOL and binary policy, plus explicit exceptions where file formats or supported workflows require them.
• Keep custom filters, Git LFS, working-tree encodings, merge drivers, archive exclusions, and repository-specific Linguist classifications opt-in unless a universal requirement is justified.
• Specify precedence per attribute and nested scope. Do not mechanically reuse gitignore's baseline-last composition model: attributes resolve individually and have different pattern rules.
• Extend the existing catalog/source/selection machinery only where the audit demonstrates a gap. Record immutable provenance and regenerate affected projections through their owners.
• Preserve repository-owned rules and reject conflicting or unsupported customization clearly.

Part 3: prove actual Git behavior and adopt the golden root

Use isolated disposable Git repositories with explicit configuration to verify:

• effective values through git check-attr;
• text normalization and checkout behavior under representative core.autocrlf configurations, including intended Windows command-file exceptions;
• binary round trips without byte changes;
• readable source/lockfile diffs and deliberate diff suppression only where accepted;
• nested/per-attribute overrides, filenames with spaces, and representative extensionless or specially encoded fixtures;
• archive membership only if export rules are selected.

Any git add --renormalize migration must be previewed and reviewed separately from semantic edits. Inspect expected blob/EOL changes; preserve binary payloads and avoid history rewriting.

Part 4: Filament pilot

• Consume accepted immutable baseline inputs.
• Select only rules justified for Filament's current files; its future IaC engine remains undecided until separate work selects it.
• Record provenance, supported local additions, update/rollback, and reproducible evidence.
• Verify attributes and blob behavior, then open one bounded consumer PR and stop for maintainer review/merge.

Part 5: integration and closeout

• Reuse the materialization/conformance/rollout seams established by the gitignore iteration.
• Holon owns generation/adoption; EgoLint owns content/behavior conformance; Relay owns execution; Pace owns reviewed rollout.
• Link owner-specific follow-ups when concrete gaps are established, reusing existing issues.
• Record upstream acceptance, golden proof, Filament adoption, reusable CI, and fleet adoption independently.
• Update the master epic and the reusable process with attributes-specific lessons.

Acceptance

• Existing rules have explicit disposition and ownership.
• A versioned, conservative universal baseline and variation contract are accepted.
• Required-file presence and meaningful content/behavior validation are distinct.
• Deterministic source/selection/provenance checks and real Git fixtures pass.
• Text migration is reviewed without unexplained binary changes or hidden content loss.
• Empathy's golden selection and Filament's accepted pinned pilot are proven.
• Update, local preservation, rollback, and remaining integration are documented.
• Every implemented part is handed off as a bounded PR; live merges are verified before advancing.

Non-goals

Selecting a universal IaC engine, adopting LFS or custom tooling everywhere, hiding inconvenient diffs to obtain a green check, bulk-renormalizing the organization, or completing unrelated MegaLinter/security debt.