Repo Health Sweep

Repo health sweep

This pass makes the repository easier to understand without changing what it means. It is not a search for short code at any cost. A smaller implementation that hides a protocol constraint, changes public behavior, or moves complexity elsewhere is worse. A comment that is shorter but no clearer is not a win either; the goal is that a reader stops re-reading.

The pass runs twice a week. Each run reviews bounded cohorts, not the whole tree. Coverage accumulates in Linear so the next run reaches code the previous one did not.

What counts

A finding needs a concrete cost and a behavior-preserving smaller shape. Every finding carries a kind:

• remove: the text or code carries nothing; delete it.
• dedupe: one owner already exists; point to it.
• clarify: the meaning stays, the reader stops guessing. The finding names the ambiguity and quotes current and proposed text.

Clarify

The repository's job is to make logging simple, and its own prose has to clear that bar. A clarify finding is any of:

• A comment, JSDoc block, or error message a reader cannot act on without reading the code it annotates.
• A JSDoc block on a public option that restates the type, repeats the docs page, or lists examples the docs already carry. The smaller shape keeps the purpose and the constraint, usually one sentence each, and nothing else. JSDoc on public APIs stays; its length is the finding.
• A paragraph comment whose durable constraint fits in one or two lines.
• A sentence in a skill, instruction, README, or PR body that can be read two ways.

The proposed text is part of the finding, not an afterthought. Without it the verifier has nothing to check and rejects the candidate as taste.

Code

• Dead imports, helpers, branches, parameters, commented-out code, or unreachable fallbacks.
• A one-use wrapper that adds no policy, transformation, authority, or test boundary.
• Duplicated implementations of an invariant already owned by one helper.
• Defensive code that masks state already validated upstream.
• A comment that only paraphrases the code.

Keep comments that explain a protocol quirk, security boundary, compatibility requirement, or deliberate trade-off; shorten them when they ramble, never drop them. Do not report a public rename or behavior change as cleanup.

Tests

• A test that reimplements source logic instead of importing and exercising it.
• Multiple tests with the same setup, action, assertion, and failure mode.
• An obsolete compatibility or regression case whose triggering source path no longer exists.
• A fixture or snapshot with no reader.
• Mock-only coverage duplicated by a test through the real framework runtime or request driver.
• An assertion that cannot fail independently of another assertion in the cohort.

A proposed removal names the surviving test and compares inputs, runtime boundary, observable output, and failure mode. Keep coverage for public contracts, past regressions, framework lifecycles, adapter protocols, type guarantees, platform-specific runtimes, and distinct edge cases. Never weaken an assertion or remove a test only because the suite is large.

Architecture

• One policy or state owned in multiple places.
• A layer that only forwards data and has no independent contract.
• An abstraction whose second use disappeared.
• Logic in Eve wiring under agent/ that belongs under agent/lib/ with a colocated test.
• A manual sequence that the installed framework now expresses directly.

Framework integrations drifting from the contract in root AGENTS.md are the self-review's lens; do not duplicate it here.

A different design is not evidence. Trace callers, exports, tests, configuration, and failure paths before proposing a boundary change.

Communication

Review both authored rules and recent output:

• apps/evi/agent/instructions.md, skills, schedules, subagent prompts, evals, and repository templates.
• Recent Evi-authored issue replies, review comments, and pull request titles and bodies.
• Docs, READMEs, examples, and AGENTS.md files when they fall in the selected cohort.

Look for answers that bury the conclusion, repeat it, narrate retrieval, expose internal detail without a user action, or sound certain beyond the evidence. Check whether instructions conflict or duplicate one another. Preserve repros, acceptance criteria, constraints, uncertainty, and explanations that help the reader act.

1. Start from a clean source

Work in /workspace/repo on the current main. Record git rev-parse HEAD; every reviewer receives that revision. Load contributing before writing an artifact.

Anything claimed about an API, option, export, adapter, example, or framework contract is read from source or executed at this revision. Absence is proven by enumerating the real surface. One counterexample kills a finding.

2. Read the coverage ledger

Keep one Linear issue on the evlog team titled Evi simplification coverage ledger. Search that exact title once with linear__list_issues, including closed issues. Keep the returned issue ID for every read and write in the run, then read its comments with linear__list_comments. In a real run, create the issue when the exact search returns none, and reopen it when it was closed; the ledger is never Done while the schedule runs. In a dry run, report the missing or closed ledger and do not change it.

Each run comment records:

• revision and date;
• exact code, test, architecture, and communication cohorts;
• skipped areas and why;
• confirmed findings and their destination;
• rejected findings with the verifier's reason;
• questions and blockers;
• next cohorts.

A rejected finding is durable evidence. Do not raise it again unless the relevant source or maintainer decision changed.

3. Choose bounded cohorts

Choose one cohort for each reviewer. Prefer the least recently reviewed eligible area. Make the four scopes non-overlapping where possible.

Code cohort: one package directory or a similarly sized part of apps/evi/agent/lib/. Name exact paths. A directory whose files are a third comment lines (packages/evlog/src/adapters/ is one) is a natural clarify cohort.

Test cohort: one bounded test directory or one source area and its matching tests. Include both source and test paths so the reviewer can trace behavior rather than compare test names.

Architecture cohort: one relationship, such as runtime to adapters, CLI rules to package exports, or Eve wiring to agent/lib/. Name both sides and the invariant being examined.

Communication cohort: one authored surface plus a small sample of recent real output. Use GitHub search and context tools to collect Evi-authored issue replies or pull requests. Include each exact URL and its complete excerpt in the workflow input. Exclude an artifact when its body is missing, JavaScript-only, or truncated, and record the retrieval limitation. Do not ask the reviewer to recover external content from a link.

Do not choose a cohort inside its cooldown when another eligible area exists. A recent change may override the cooldown when the diff itself is the reason for review.

4. Run the workflow once

Call simplification-sweep with:

• the recorded revision;
• the four exact scopes;
• every relevant rejected finding or maintainer decision from the ledger.

The tool first verifies that the shared checkout matches the supplied full commit SHA. A mismatch ends the run before any specialist starts. It then fans out to hidden read-only specialists:

1. code_simplifier;
2. test_reviewer;
3. architecture_reviewer;
4. communication_reviewer.

After all four settle, finding_verifier tries to disprove every candidate against the same checkout. The workflow assigns finding ids and keeps the candidate fields itself; the verifier returns a verdict, delivery, and verification per id. The workflow returns reviewer status, limitations, programmatic counts, confirmed findings, rejected findings, open questions, and pullRequestBatches: confirmed pull-request candidates grouped by kind and directory. Read status, reviewers, and counts before the findings. A degraded run has missing evidence and cannot produce a pull-request-ready finding. A verification that returns no usable result degrades the run and marks every candidate as a question rather than failing the sweep. A recovered run may proceed, but the final report names the recovered failure. Copy counts from the result; never count finding IDs in prose. Do not bypass verification or ask the root model to recreate a failed specialist's report from memory.