Build composable repository and organization audit orchestration

[szmyty]

Outcome

Turn Reflector's existing reflective-auditing direction into a reusable, pass-based orchestration layer that can run Aether-owned audit profiles across one repository or an organization fleet while preserving repository-local audit evidence and strict read-only defaults.

Reflector should execute and compose analysis; it must not become the canonical owner of audit semantics. Aether owns reusable audit specs/profiles/skills. Hygiene owns policy/applicability. Observatory owns normalized fleet read models. Relay owns Repository Intelligence publication.

Why this belongs in Reflector

Reflector already frames recursive engineering as a synchronization and auditing problem and has historical design work around pass-based organization analysis. The missing product boundary is a real orchestration path that can:

organization/repository selection
        ↓
resolve Aether audit profile(s)
        ↓
discover immutable repository revisions
        ↓
execute independent evidence-gathering/audit passes
        ↓
persist repository-local reports + run manifest
        ↓
produce organization run index
        ↓
hand normalized evidence to Observatory / downstream issue review

Dependencies

• Audit profiles and report metadata: egohygiene/aether#86
• Existing Aether reflector/auditor specifications should be reconciled rather than copied.

Execution model

Define explicit passes such as:

1. fleet/repository discovery;
2. context and capability discovery;
3. per-repository audit execution;
4. cross-repository relationship observations where authorized;
5. audit result normalization/indexing;
6. candidate backlog synthesis;
7. human review/export boundary.

Later passes must consume prior pass artifacts rather than repeatedly rediscovering the same state when the represented revision and inputs have not changed.

Run contract

A run should declare at least:

• organization/repository scope;
• exact represented revisions;
• selected audit profile IDs/versions;
• include/exclude filters;
• depth/budget/concurrency limits;
• local/offline requirements;
• provider/model selection when AI is used;
• network policy;
• output root;
• resume/retry behavior;
• whether candidate issue synthesis is enabled;
• whether any downstream mutation is authorized.

Default behavior must be read-only and must not create GitHub issues.

Local-first / offline direction

The orchestration contract should support the long-term goal of running with local models and local repository checkouts:

• deterministic repository discovery and evidence collection should not require an LLM;
• model/provider adapters must remain replaceable;
• a local model may execute Aether skills without changing the audit contract;
• network-dependent evidence must be declared explicitly and degrade to unknown/unavailable when disabled;
• the audit artifacts must remain useful even when no model is configured for recommendation synthesis.

Do not couple the architecture to ChatGPT, Copilot, or one local model runtime.

Organization run artifacts

Produce a deterministic run index/manifest that references repository-owned audit reports rather than centralizing duplicate copies of their prose.

Suggested shape:

audits/runs/<run-id>/
  manifest.json
  summary.md
  repositories.json
  findings.json
  candidate-backlog.json

Repository reports remain canonical in their owning repositories/worktrees. The organization run records references, digests, represented revisions, profile versions, status, and safe aggregate metadata.

Candidate backlog boundary

Reflector may synthesize a proposed backlog from audit findings, but:

• source finding IDs must be preserved;
• duplicate/overlapping findings should be grouped explicitly;
• experimental ideas must stay distinct from defects/conformance gaps;
• issue creation requires a separate human-authorized step/tool;
• generated backlog output is a proposal, not proof that work is required.

Resume and scale

Support bounded parallelism across repositories without losing determinism:

• resumable runs;
• repository-level checkpoints;
• explicit partial/blocked/unavailable states;
• no re-running unchanged completed work unless requested;
• cancellation without corrupting historical evidence;
• stable manifests that make it clear which repositories were and were not inspected.

Acceptance criteria

• Reflector can resolve and execute Aether audit profiles without copying their semantics.
• One command/config can target one repository, a filtered fleet, or all eligible repositories.
• Exact repository revisions and profile versions are captured before execution.
• Deterministic discovery/evidence collection can run without a remote LLM.
• Provider/model selection is replaceable and compatible with local/offline execution.
• Organization manifests reference repository-local canonical reports rather than replacing them.
• Runs support bounded concurrency, partial completion, cancellation, and resume.
• Candidate backlog synthesis preserves source findings and uncertainty.
• No GitHub issue, PR, commit, or repository mutation occurs by default.
• Synthetic fixtures prove mixed complete/partial/blocked repositories.
• Outputs are suitable for Observatory ingestion without prose scraping.

Non-goals

• Owning the canonical audit-profile taxonomy.
• Replacing Hygiene policy or EgoLint/Relay validation.
• Building the Repository Intelligence UI.
• Automatically fixing findings.
• Automatically opening every suggested issue.