🧱 [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.
• Complete a linked Filament adoption PR after the upstream baseline is accepted.
• Link bounded Holon/EgoLint/Relay/Pace follow-ups only where inspection finds a real missing integration; reuse existing issues before creating new ones.

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 current catalog already requires .gitignore but marks its content repository-owned; egohygiene/empathy#82 is the work to establish the stronger layered baseline. Copying the current file into Filament alone does not complete that issue.

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.

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.

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.
• Roadmap: complete the Repository Intelligence and Organization Intelligence visual control plane #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 closed; #85–#88 verified merged	Pending validation/acceptance follow-up	Golden-root adoption accepted. Next: focused foundation validation cleanup, then reconcile remaining gaps before the pilot.
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 — iteration 01, part 3 merged; validation cleanup next

• Accepted upstream: Empathy #85–#87 are verified merged. #87 merged as 8e1b748c5b72c0036763e1528f1ffe14cecd99df, accepting foundation 1.1.0 composition/catalog integration.
• Latest accepted PR: Empathy #88 merged on 2026-09-18 as 2afbdca3e916647c67ace4e231ca6bde22486307. Main and the exact reviewed tree were verified; no additional review decisions or open Empathy PRs were present.
• Accepted outcome: 176 root rules became 80 composed rules, with actual output/private-material scopes and the accepted universal baseline last. All 176 old rules have an evidence-backed disposition; 269 real Git path expectations and exact plan/root comparison prove the migration. A path-only audit found no newly visible pre-existing ignored files.
• Validation: 115 root tests run, 113 passed, two expected Identity skips; relevant lint/schema/generator/workspace checks pass locally. All six PR workflows completed: MegaLinter fast profile, CodeQL, dependency review, and commit validation passed. Automation confirms the root suite result, then fails only the existing EgoLint pin mismatch. OSV remains red at its existing high-severity gate (84 findings). MegaLinter's pre-command syntax diagnostic remains documented in #88. No all-green CI claim.
• Remaining acceptance: the latest full MegaLinter snapshot also exposes earlier foundation typing/import and assertion-security findings. The fast PR profile is not full-profile proof. Inherited nested-ignore exceptions and existing root Cargo fixture wiring are documented. These validation/content boundaries must be reconciled before complete #82 acceptance; detail and source links are in the owning issue.
• Resume record: part 3 checkpoint; migration evidence.
• Next bounded part: fix foundation-tooling/test typing and import resolution, replace assertion-only runtime guards, and verify the components against the actual full-profile configuration plus existing Git behavior tests. Recommended scope only; no implementation has started. Inspect the merge-triggered full scan when it completes. Then reconcile remaining CI pin/bootstrap failures, inherited policy exceptions, and full acceptance before the pinned Filament pilot.
• Following adoption: Filament selects its own local facts against an accepted immutable source; it must not copy imported Empathy ignore policies. Holon materialization, EgoLint content conformance, Relay execution, and Pace fleet convergence retain their owners.
• Stage: upstream merged for golden-root adoption. GitHub closed #82 when #88 merged; preserve that closure. Its unchecked environment/full-validation criteria remain explicit follow-up work here. Filament proof, reusable conformance, and fleet rollout remain pending; this epic stays open.
• Refreshed 2026-09-18 after verifying #88's merge. Continue one bounded PR per review/merge/sync cycle; no self-merge.

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.