🧱 [MASTER EPIC] Solidify repository file contracts, one file at a time

[szmyty]

Outcome

Establish one repeatable, reviewable process for solidifying Ego Hygiene repository file contracts, one target file at a time, using egohygiene/filament as the pilot consumer.

A future chat should be able to open this epic, see the current file and verified stopping point, and continue the same workflow without reconstructing the organization from conversation history.

This epic owns cross-repository coordination and the working process. Canonical policies, baseline artifacts, validators, generators, and repository-specific content remain with their existing owners.

Working agreement

• Start with .gitignore, using the existing 🧹 Define a conservative layered .gitignore baseline and profile ownership empathy#82 scope.
• The maintainer chooses the next file; future candidates do not become requirements merely by appearing in this epic.
• One iteration addresses one logical file contract. Supporting catalog, schema, fixture, test, documentation, and continuity changes may involve several files.
• Use one bounded outcome per PR and linked PRs where an iteration spans repositories. Return after each bounded PR and pause for maintainer review, merge, and sync before starting the next part.
• For each selected file, briefly explain its purpose, owner, proposed behavior, and checks before implementation. Resolve routine implementation choices within the authorized scope; surface material policy decisions clearly.
• Keep the handoff small: what changed, validation, PR links, remaining blockers, and the exact next action.
• The maintainer reviews and merges. Reverify live state after a merge before continuing.
• Completion of this infrastructure program is not a prerequisite for unrelated creative or product work.

Canonical ownership

Concern	Owner
Organization policy, applicability, repository catalog, cross-repository boundaries	Hygiene
Golden repository baseline, selectable profile composition, integration proof	Empathy
Repository file generation and blueprint materialization	Holon
Lint semantics and conformance validation	EgoLint
Reusable GitHub workflow execution and evidence delivery	Relay
Normalized observations, dependency graph, provenance, freshness, queries	Observatory
Reviewable fleet adoption, dependency ordering, and current focus	Pace
Portable agent instructions, skills, and completion procedures	Aether
Cross-repository coordination and issue routing	Organization .github
Repository-specific facts, intent, and local extensions	Each consumer; Filament is the first pilot

Filament retains its reusable infrastructure-as-code responsibility. Piloting these files does not move governance or template ownership into Filament.

References: issue routing, Hygiene agent context, Empathy foundation contract, and Empathy ownership decision.

Contract record for every file

Keep applicability separate from content ownership. For example, an architecture file may be universally required while its facts remain repository-authored.

Field	Record for the selected file
Purpose and path	What problem it solves and its canonical location
Applicability	Universal, selected profile/capability, optional, exempt, or not applicable
Canonical authority	Policy/specification, implementation owner, and existing issue
Content model	Repository-authored; baseline plus explicit local additions; generated; or inherited by reference where supported
Upstream identity	Contract version and immutable source/artifact reference where consumed
Local variation	Permitted overlays, exceptions, and repository-owned sections
Update behavior	Generate, merge, preserve, detect drift, and recover/roll back
Validation	Presence, required content, behavior, provenance, and useful failure messages
Adoption	Pilot evidence, migration status, and advisory/enforcement stage

Extend existing catalogs and schemas only for demonstrated gaps. File existence alone is not conformance; an empty or inappropriate file must not satisfy a meaningful contract. Organization-inherited defaults should not be copied into every repository without a local reason.

Reusable iteration checklist

Use this checklist for every selected file:

• Discover: inspect live branches/issues/PRs and applicable instructions, architecture, decisions, contracts, roadmap, continuity, and relevant CI. Reuse existing work and preserve concurrent changes.
• Define: complete the file's contract record, identify the smallest implementation scope, and record genuine prerequisites with their satisfaction conditions.
• Implement upstream: change the baseline or specialist source in its owning repository; update affected catalog/schema/projections and meaningful tests.
• Prove composition: demonstrate that selected profiles, local ownership, provenance, and repeated resolution behave correctly.
• Adopt in Filament: consume accepted immutable inputs; preserve local content and add only applicable overlays. Link the consumer PR to its upstream work.
• Connect validation: use the owning validator and Relay integration when available. Record any pending integration explicitly; distinguish local proof from reusable CI and fleet rollout.
• Review: run relevant checks using the actual CI configuration, inspect completed PR checks and the complete diff, reconcile material ADR/roadmap/continuity impact, and present bounded PRs with evidence.
• Close the loop: after verified merges, update this epic's ledger and the affected issues/dependencies; close work only against its own acceptance criteria; identify the next action.

A file iteration may finish as an accepted Filament pilot while broader rollout remains tracked. Report upstream contract, materialization, pilot, CI integration, and fleet adoption separately so partial delivery never appears complete.

Track A — file contracts and Filament pilot

Iteration 01: .gitignore

• 🧹 Define a conservative layered .gitignore baseline and profile ownership empathy#82 — issue closed after #88 merged; baseline/composition/golden-root work accepted. The original environment/full-validation acceptance gaps remain tracked follow-up work before this upstream scope is fully reconciled.
• fix(foundation): reconcile full-profile typing and runtime guards empathy#89 — scoped foundation typing/runtime-guard cleanup; PR #90 verified merged.
• Adopt the pinned universal gitignore baseline as the file-contract pilot filament#5 — PR #6 verified merged at c3eb64b8087face7504e7571dc8396c19525649f; exact tested tree, 14 passing local tests, manual pilot accepted.
• Link bounded Holon/EgoLint/Relay/Pace follow-ups where inspection establishes missing integration; the owner-specific sequence is below.

Follow egohygiene/empathy#82's full acceptance criteria. In particular, prove both ignored local state and intentionally visible source, lockfiles, examples, shared configuration, and reviewed artifacts. Avoid unconditional universal rules for ambiguous paths such as bin/, build/, dist/, target/, and vendor/. Never infer that an ignored path is safe to delete.

Empathy's accepted foundation 1.1.0 keeps .gitignore required and repository-owned while registering the universal/profile composition sources. Filament consumes those sources with its own explicit selection; copying Empathy's repository-specific root is not the adoption model. The manual pilot does not resolve all historical egohygiene/empathy#82 validation gaps.

Keep Holon materialization and Pace fleet convergence as downstream concerns, as egohygiene/empathy#82 specifies. If a reviewed pinned manual pilot is useful before automated materialization is ready, label that limitation and track the remaining integration.

Remaining gitignore completion sequence

The source contract and manual pilot are accepted. The complete reusable workflow and rollout remain active work. Continue one bounded PR per review/merge/sync cycle.

Order	Issue / owner	Outcome	Readiness and dependency meaning
1 — merged	Holon #58 / PR #60	Plan/adopt/update/verify/rollback the pinned ignore selection while preserving local rules.	Planner PR #59 and lifecycle PR #60 are merged; #58 is closed. Accepted lifecycle merge: 660b941f99618806fcadd589bcdae61c519f96e4.
2 — review	EgoLint #61	Validate provenance, content, effective Git behavior, and nested overrides.	PR #62 implements the native validator and passes local checks; published-head CI is running. Maintainer review/merge is next.
3	Empathy #92	Reconcile inherited exceptions and prove the golden/Filament consumer through shared interfaces.	Full proof requires accepted Holon/EgoLint inputs; owner/source classification can proceed independently.
4	Relay #5 / #49	Run the governed validator through shared CI and retain useful evidence.	Reuse existing issues and their release/capability/mode prerequisites. File-specific conformance is a consumer scenario, not a new blocker for shipping the general workflow.
5	Pace #30	Adopt the contract through reviewed repository waves and verify actual convergence.	Live rollout waits for compatible accepted materialization, validation, and shared execution. Coordinate workflow rollout with Pace #20.

The original #82 environment/full-suite gaps now have an explicit reconciliation owner in Empathy #92. Broader repository debt remains visible and separately scoped. Direct MegaLinter repairs remain deferred to EgoLint/Relay adoption; this queue does not silently reactivate that work.

Do not label the entire gitignore path complete while required integration or agreed rollout stages remain open. At closeout, record completed, explicitly deferred, excepted, and still-blocked stages separately; confirm the agreed adoption wave and remaining boundaries before advancing the file ledger.

Shared validation:

• Validate architecture and repository structure in CI relay#5 — reusable architecture, required-file, dependency-boundary, and generated-ownership validation, consuming Hygiene/EgoLint rules.

Iteration 02: .gitattributes — selected and queued

• Roadmap: solidify the universal gitattributes contract and Filament pilot empathy#91 — audit the existing attributes file, establish the universal/optional rules and contract, prove actual Git behavior, and adopt accepted immutable inputs in Filament.
• The current Empathy catalog already requires this file. Inspect and strengthen its existing content rather than treating presence or a copied file as sufficient.
• Planned parts: rule audit/specification → baseline/catalog/variation contract → golden behavior and migration proof → Filament pilot → remaining owner-specific integration and closeout.
• Review text/EOL behavior, justified Windows exceptions, binary integrity, useful diffs, nested/per-attribute overrides, and safe normalization. Custom filters, LFS, archive exclusions, and specialized metadata require an explicit applicability decision.
• The maintainer selected this as the next file after the gitignore completion sequence. That is scheduling intent, not an invented technical dependency; implementation has not started.

Later file iterations are selected by the maintainer and added to the ledger below. Do not bulk-implement an assumed universal file list.

Track B — reliable organization context and work selection

These issues make the same workflow easier to resume across repositories. Their inclusion is a coordination relationship, not a declaration that every issue blocks .gitignore.

Reconciliation and execution map

• Reconcile the legacy issue backlog with repository ownership and native dependencies #23 — one-time backlog ownership and native-dependency reconciliation.
• 🧭 Establish a dependency-aware portfolio map and focus queue pace#25 — dependency-aware portfolio map, independent work, and reviewed focus queue.
• Define recurring organization health checkpoints and keep the repository catalog live hygiene#36 — catalog freshness and recurring organization checkpoint policy.
• Build the normalized Repository Intelligence graph and query snapshots observatory#7 — existing normalized graph/query foundation; reuse the implementation and verify its inputs and coverage.

Organization roadmap and aggregation

• Define the canonical organization roadmap and repository-roadmap inheritance contract hygiene#60 — canonical organization roadmap and repository-roadmap composition contract.
• Build a normalized organization-roadmap and cross-repository initiative read model observatory#22 — normalized organization-roadmap and cross-repository initiative model.

Agent maintenance and adoption

• Add roadmap-impact reconciliation as a completion hook for repository-changing agents aether#88 — roadmap-impact reconciliation at PR handoff.
• Roll out continuous roadmap reconciliation across the repository fleet pace#29 — fleet adoption of roadmap reconciliation.
• Roll out repository continuity handoffs across the Ego Hygiene fleet pace#26 — continuity handoffs and agent guidance across repositories.

Linked presentation and broader programs

• Add an organization-level /roadmap/ quest-line to Organization Intelligence #29 — organization roadmap UI.
• [EPIC] Finish Repository Intelligence, Organization Intelligence, and site control-plane surfaces #30 — Repository/Organization Intelligence visual-control-plane tracker.
• Roadmap: make audits, hygiene, and organization intelligence a continuous control loop hygiene#58 — continuous audit, conformance, and intelligence loop.
• Roadmap: prove Ego Hygiene as a reusable organization platform with a second consumer hygiene#43 — broader reusable-organization-platform proof.

These existing umbrella programs retain their own scope and children. This epic does not reparent them, duplicate their implementation checklists, or make all dashboard delivery a file-pilot gate.

Dependency rules

• Distinguish execution prerequisites from artifact consumption, parent/child grouping, and conceptual relationships.
• Prefer native GitHub blocking relationships for confirmed issue blockers, with a reason and explicit unblock condition.
• Record whether dependencies are reviewed with prerequisites, reviewed with none, or not yet reviewed. An empty list alone does not prove independence.
• Derive readiness from current scope, satisfied prerequisites, available evidence, required decisions, and competing PRs. Keep ready, active, blocked, unknown/stale, and deferred distinct.
• Check the actual completion condition: a merge may satisfy some dependencies; another consumer may need a published immutable artifact. Issue closure alone is insufficient evidence.
• Keep inferred relationships separate from confirmed ones, and readiness separate from priority.
• Refresh the affected graph neighborhood after material issue, PR, release, or ownership changes.

The eventual agent entry point should link the Hygiene catalog, relevant GitHub work, Observatory snapshot, and Pace focus view. Generated maps remain projections with timestamps, revisions, and source links; they do not replace repository-owned requirements.

Iteration ledger

Maintain this as a compact current-state index. Detailed history stays in issues and PRs.

Iteration	Target	Upstream work	Filament proof	State / next action
01	.gitignore	egohygiene/empathy#82 and egohygiene/empathy#89 closed; accepted source/composition/golden root	egohygiene/filament#5 / egohygiene/filament#6 verified complete	Holon #58 is complete via merged PR #60. Active review: EgoLint PR #62 for #61. After merge, continue with Empathy #92, then existing Relay/Pace stages.
02	.gitattributes	Empathy #91 — audit existing required file and strengthen the content contract	Pending accepted immutable baseline	Selected and queued after gitignore closeout; no implementation started.
Next	Maintainer-selected file	Resolve existing owner/issue	Pending	Not selected

Recommended stage vocabulary: selected, specified, upstream PR, upstream merged, pilot PR, pilot verified, blocked. Add a short reason and source link whenever work is blocked.

Integration acceptance criteria

• Each selected file has explicit applicability, source/content ownership, local-variation rules, and validation.
• New requirements land in the canonical owner/catalog and have a traceable path to consumer adoption.
• The .gitignore iteration satisfies its upstream scope and has verified Filament proof.
• Materialization, local validation, reusable CI, and fleet adoption are reported independently with any remaining gaps linked.
• The process can be reused for a subsequent maintainer-selected file without redesigning its stages.
• This epic provides current issue/PR links, blockers, evidence, and the next action for a fresh chat.
• Confirmed dependency changes are reflected in the owning issues and available graph/focus projections.
• Portable process guidance is extracted into its proper owner when the proven workflow warrants it; consumer instructions reference that source.

The initial workflow is proven after .gitignore and one subsequent selected file complete the relevant upstream and pilot checks. Keep this epic open until the maintainer-defined file inventory and agreed integration scope are reconciled; broader programs retain their own completion criteria.

Fresh-chat resume instruction

Continue this repository-file contract epic. Read its current ledger and the active file's owning issue. Verify live GitHub state, applicable AGENTS.md/architecture/contracts/CONTINUITY.md, dependencies, and open PRs before acting. Explain the selected file briefly, then execute one authorized bounded step through validation and a reviewable PR. Update the ledger/checkpoint with evidence and the next action. Use Filament as the pilot, preserve canonical ownership, and do not merge your own PR. Do not begin unrelated files or infer that empty dependency metadata means work is independent.

Current checkpoint — EgoLint validator PR ready for review

• Accepted source/pilot: Empathy foundation 1.1.0 at b44f798bb49259f9f48416b4ffebde1103e135c0; Filament PR #6 merged as c3eb64b8087face7504e7571dc8396c19525649f.
• Holon complete: PR #60 is verified merged as 660b941f99618806fcadd589bcdae61c519f96e4, and #58 is closed. Its complete local lifecycle passed run 35407514444 on reviewed head 72890e785933075d7d37b2a8c11d8226682c1f0f.
• Current review: EgoLint PR #62 addresses #61. Open/unmerged head: 24eda6da5c3d11279f86fca8e79ac4d438a4ba59; published/tested tree: dc2ca92d454bae9ab6538f9ebd26737f23e97558.
• Candidate behavior: focused native gitignore validation, exact pinned composition/content checks, isolated real Git behavior, nested-policy inventory, tracked-path checks, and separate coverage results. Missing Git/incomplete evidence blocks a clean result; exact reviewed exceptions remain visible. Ordinary file payloads are not read or copied by this command.
• Local validation passed: Rust 1.85.1 formatting/Clippy; 140 Rust tests including 19 native gitignore and 6 CLI tests; 62 Python tests; 11 JavaScript tests; 18 CLI schema comparisons; crate packaging; final native continuity validation.
• Published-head CI: CI run 35411053785 and Dogfood 35411053761 remain partially in progress on the corrected head. Rust core (including formatting, Clippy, tests, packaging), Linux/macOS/Windows native rules, schemas, contracts, the CLI image build/smoke test, both JavaScript workflows, and Identity have passed. The catalog COPY omission is fixed. Only the full-policy image and Dogfood remain running at this handoff; their completion is not claimed.
• Durable continuation: PR #62 updates the gitignore contract guide, architecture seam, ADR-004 proposal, EGL-Q08, schemas/packaging, fixtures, and CONTINUITY.md. The existing continuity validator remains at observe for its separate #55 upstream-release gate.
• Exact next action: maintainer reviews/merges PR #62 with the relevant checks. Verify that merge and #61 closure; then Empathy #92 is the next scheduled bounded proof using accepted/pinned Holon and EgoLint inputs.
• Following work: Empathy #92 → existing Relay 💰 [platform] Complete GitHub Sponsors profile (szmyty) #5/#49 integration when inputs are available → Pace [EPIC] Finish Repository Intelligence, Organization Intelligence, and site control-plane surfaces #30. Inherited-ignore and historical #82 proof gaps remain with Empathy #92; no whole-Empathy conformance, shared rollout, or organization graph implementation is claimed.
• Deferred/queued: direct MegaLinter repairs remain deferred. Empathy #91 keeps universal gitattributes selected after agreed gitignore closeout.
• Refreshed 2026-09-19 for PR #62. Stop at maintainer review; do not self-merge or begin the next owner issue.

Initial checkpoint

• Created at the maintainer's request on 2026-09-17.
• Existing issues above were re-fetched before creation; Build the normalized Repository Intelligence graph and query snapshots observatory#7 is closed, and the other linked issues remain open at this checkpoint.
• Discovery and the proposed workflow are complete. No baseline implementation or Filament adoption is claimed.
• This is the durable coordination record for the chat-driven file workflow; it contains the process rather than depending on a chat attachment.
• Trust boundary: public repository coordination and reviewable code/documentation changes. Credentials, deployment state, publication authority, and unrelated account operations remain outside this epic.