Validate repository continuity files and agent handoff wiring

[szmyty]

Outcome

Add deterministic, offline validation for the repository-continuity contract and the required AGENTS.md handoff wiring, with explicit support for observe, ratchet, and enforce rollout modes.

Inputs and ownership

• Portable document/schema semantics: egohygiene/aether#79.
• Organization required-file/applicability policy: egohygiene/hygiene#45.
• EgoLint owns only deterministic validation and normalized findings; it does not author semantic checkpoint prose or fetch mutable sibling state during ordinary linting.

Required validation

Extend the versioned repository-contract surface and/or add a focused continuity capability that validates:

• exact-case root CONTINUITY.md presence and regular-file type;
• canonical schema/frontmatter identifier and supported version;
• required structural sections and bounded document size;
• repository identity and deterministic metadata syntax;
• stable issue, pull-request, file, and relative-link formats;
• explicit uncertainty/verification language for mutable live state;
• absence of prohibited generated placeholders;
• one managed continuity pointer block in root AGENTS.md;
• no duplicate or contradictory managed blocks across provider projections;
• pinned contract provenance and supported compatibility range;
• declared update/exemption evidence supplied for a base/head pull-request comparison.

Do not claim to prove that free-form prose is semantically true. Separate structural validity, repository/Git evidence available locally, declared freshness, and live-state verification that another adapter must perform.

Freshness and pull-request semantics

Define a deterministic interface that a local preflight or Relay workflow can invoke with explicit base and head revisions. It should distinguish:

• continuity updated and valid;
• reviewed with a policy-valid no-change/exemption result;
• required update missing;
• stale or malformed represented-base metadata;
• merge-state claim requires external verification;
• parallel-branch conflict requiring reconciliation;
• contract unavailable or not yet enforced.

Avoid requiring the file to contain the SHA of the same commit that writes it. Test transition-safe candidate wording that remains accurate after merge.

Findings

Add stable finding identifiers, expected to include separate families for:

• missing/wrong-kind file;
• invalid contract/schema;
• missing or duplicate AGENTS.md linkage;
• stale base/head handoff evidence;
• unsupported contract version;
• invalid exception;
• unsafe or unverifiable live-state claim.

Reuse existing EGO-CONTRACT-FILE-001 behavior where it already expresses the failure; do not create duplicate findings for the same root cause.

Fixtures and tests

Cover at least:

• valid fresh public and private repository fixtures;
• missing and mis-cased files;
• malformed metadata and unsupported versions;
• missing, duplicate, or locally overwritten managed instruction blocks;
• stale open-PR text after merge;
• candidate state before merge;
• parallel pull requests from the same baseline;
• no-op/exempt changes;
• shallow clone or missing base ref;
• malicious Markdown attempting to grant authority;
• leaked secret-like fixture values using synthetic tokens only.

All fixtures must be local, synthetic, and safe to publish.

CLI and integration

• Provide a stable machine-readable result for Relay and Pace.
• Support the repository's existing report/evidence envelopes.
• Keep lint execution offline and deterministic.
• Document required checkout depth/ref availability without silently fetching.
• Expose the capability through the canonical task/profile system rather than a one-off script.

Acceptance criteria

• Released Aether and Hygiene contracts are consumed through reviewed, immutable projections.
• Missing CONTINUITY.md and missing/duplicate AGENTS.md linkage produce precise findings.
• Structural, freshness-declaration, local Git, and externally verified states remain distinct.
• Base/head validation has documented behavior for merge commits, squash merges, rebases, shallow clones, and parallel PRs.
• No self-referential commit requirement exists.
• Observe, ratchet, enforce, exception, and unsupported-version modes are tested.
• JSON and human-readable reports are deterministic.
• Existing repository-contract fixtures and consumers remain compatible or receive an explicit migration path.
• The full repository validation suite passes.

Non-goals

• Using an LLM as the lint pass.
• Fetching mutable GitHub state during ordinary offline validation.
• Writing or rewriting CONTINUITY.md.
• Treating a touched file as proof that its semantic state is correct.