maintenance git:20260720.da06232A

Immutable. This exact content is served forever at /api/v1/blob/173a6f72123212fe.

---
name: maintenance
description: Goal-oriented repository maintenance and release-readiness work for yolop. Use when the user asks for maintenance, release prep, repo health review, dependency refreshes, spec/docs alignment, test gap review, or general cleanup without prescribing an exact sequence.
metadata:
  internal: true
user-invocable: true
---

# Maintenance

Goal: leave the repo materially healthier and closer to release-ready, with evidence.

This skill implements [`specs/maintenance.md`](../../../specs/maintenance.md). Keep operational guidance here. Keep design intent and constraints in the spec.

This skill is outcome-oriented. Choose the smallest set of actions that closes the real maintenance risk in front of you.

## When To Use

- release-readiness review
- CI health on `main`
- dependency refreshes (especially the `everruns-*` family)
- spec or docs drift
- feature-completeness drift across CLI / TUI / specs / README / tests
- test coverage gaps
- code simplification / removing over-abstraction and dead code
- security hygiene review
- performance review of recently changed code
- AGENTS / skills / command hygiene

## Required Outcomes

1. **The maintenance scope is explicit.** If the user provided one, use it; otherwise state the inferred scope.
2. **The work produces concrete improvement.** Fix small/local issues; capture crisp findings for the rest.
3. **Validation matches risk.** Run checks that prove the updated areas are healthy.
4. **A release claim is backed by evidence.** Do not declare release-ready unless the changed surfaces were actually checked.

## Operating Model

- Start from goals and risk surface, not checklist order.
- A red CI on `main` outranks every other scope. Fix it first or open an issue and report the pass as blocked.
- Highest-signal first: recent diffs, failing checks, stale specs, outdated `everruns-*` versions.
- Skip untouched areas with a reason. Prefer fixing over reporting.
- For bugs uncovered, prefer a failing test before the fix when practical.
- Keep changes PR-sized. Defer anything larger to a GitHub issue and record the issue number in the report.

## Maintenance Surfaces

### CI Health

- check the latest workflow runs on `main` (`gh run list --branch main --limit 5`, through Doppler if GitHub auth fails directly)
- any red run is a hard gate: the pass is not complete while `main` is red
- if the failure is out of reach, open an issue with the failing run linked and report blocked

### Dependency Health

The `everruns-*` family (`everruns-runtime`, `-core`, `-anthropic`, `-openai`,
`-integrations-duckduckgo`) is the single most important dependency vector for
yolop. Keep them in lockstep at the same minor version.

Actions:
- check the latest version of each `everruns-*` crate (`cargo search everruns-runtime --limit 1`)
- bump them together — mixing minor versions is a soft API break
- run `cargo update` for transitive dependency drift
- check `ratatui`, `crossterm`, `clap`, `tokio` minors; they tend to ship breaking-feeling clippy/lint changes
- flag deprecated crates and identify replacements
- review `cargo tree --duplicates` for split transitive versions; fix or note why unfixable
- run `cargo audit` when available; otherwise check the repo's Dependabot alerts
- grep for direct dependencies no longer used in `src/`

Good evidence:
- `cargo build` + `cargo test --all-features` after bumps
- a successful smoke test (`doppler run -- cargo run -- --provider openai -p "hi"`) against at least one real provider

### Upstream Mirror Hygiene

Yolop began as `examples/coding-cli` in `everruns/everruns`. When upstream lands
useful changes:

- compare `src/` against the latest upstream example
- mirror non-everruns-specific improvements (UI tweaks, bug fixes, capability
  wiring) — leave behind anything tied to internal everruns paths
- record meaningful divergence as a comment near the diverged code, not a separate doc

### Specs And Docs Alignment

- changed behavior reflected in `specs/`, `README.md`, `docs/`, or `AGENTS.md`
- stale duplicate prose removed in favor of links to source files
- README provider and model lists match `runtime.rs`

### Feature Completeness Drift

A feature is ready only when its surfaces agree: CLI flags, TUI behavior,
`specs/`, `README.md`, `docs/`, tests, bundled `skills/`.

- diff `clap` definitions in `src/` against the README flag table
- check recently shipped features (see `git log` since the last tag) for a test that exercises them and a spec/README mention
- outcome: a small reconnecting fix, or a finding naming the missing surface and user-visible impact

### Code Simplification And De-Abstraction

A first-class maintenance surface, not just incidental cleanup on touched
files. A deep pass actively hunts for complexity the codebase no longer earns.
Bias toward deleting code: the best maintenance often removes more than it adds.

On code touched during the pass, always:

- delete dead code, unreachable branches, commented-out blocks
- drop TODOs that are already resolved

On a deep pass, also scan for and collapse over-abstraction:

- **Single-use abstractions** — traits with one impl, a wrapper type that only
  forwards, a generic with one instantiation, a builder for a two-field struct.
  Inline them unless the seam is load-bearing (a real second impl, a public
  extension point, a test double that earns its keep).
- **Premature generalization** — code shaped for hypothetical futures instead of
  current needs. Delete the unused flexibility; the git history keeps it.
- **Indirection with no payoff** — a helper called once that only renames a
  standard-library call, a module that re-exports one item, a config knob no
  caller sets to anything but the default.
- **Duplication that wants a helper** — the inverse: the same 5+ lines pasted in
  three places is under-abstraction. Consolidate only when it genuinely reduces
  total code and reads clearer, not to chase a DRY score.
- **Deep nesting and sprawling match arms** — flatten with early returns, `let
  ... else`, or extracted functions where it lowers cognitive load.
- **Unclear names** — rename functions, variables, and types so intent is
  legible without chasing definitions.

Guardrails: keep each simplification small and independently reviewable; do not
bundle a de-abstraction sweep with an unrelated fix. Verify with
`cargo build`, `cargo clippy`, and `cargo test` — a simplification that changes
behavior is a bug, not a cleanup. Removing a public API from a published crate
(`yolop-yep`, `tuika`) is a breaking change: note it in the PR and confirm no
external contract depends on it. When a simplification is too large to land
inline (a cross-cutting abstraction with many call sites), defer it to a
GitHub issue naming the abstraction and why it no longer pays its way.

### Security And Threat Posture

Yolop's threat surface is the host machine: filesystem and shell.

- verify the write blocklist in `runtime.rs` still covers `.git/`, `node_modules/`, `target/`, `dist/`, `build/`, `.next/`, `.venv/`, `venv/`, `.tox/`, `.gradle/`
- verify the bash tool still enforces a wall-clock timeout and per-stream output cap
- verify session JSONL log permissions stay at `0o600` on Unix
- confirm provider API keys are only read from process env, never logged or persisted to the session log

### Test And Runtime Confidence

- `cargo test --all-features` clean
- live integration test (`tests/integration.rs`) passes under Doppler
- offline smoke (`cargo run -- --provider llmsim -p "hi"`) prints a non-empty response and exits 0

## Common Evidence Commands

- `cargo fmt --check`
- `cargo clippy --all-targets --all-features -- -D warnings`
- `cargo test --all-features`
- `cargo search everruns-runtime --limit 1`
- `cargo outdated` (when available)
- `cargo audit` (when available)
- `doppler run -- cargo run -- --provider openai -p "summarize this repo in one paragraph"` — live provider smoke
- `cargo run -- --provider llmsim -p "hi"` — offline smoke

## Deliverable

Report:

- what scope was covered
- what was fixed or found
- what evidence was gathered
- deferred findings, each with its GitHub issue number
- what was intentionally skipped and why
- **blocked** status if `main` CI is red and out of reach

If the user asks to ship after maintenance, hand off to [`/ship`](../ship/SKILL.md).