git:20260720.da06232 to git:20260724.6548f64

19 added, 10 removed. Audit A to A.

---

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.

+ 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, knowledge/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 implements [`knowledge/specs/maintenance.md`](../../../knowledge/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

+ - knowledge or docs drift

+ - feature-completeness drift across CLI / TUI / knowledge / 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.

+ - Highest-signal first: recent diffs, failing checks, stale knowledge, 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

+ ### Knowledge 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

+ - read `knowledge/index.md`, then inspect concepts affected by behavior changed

+ since the last maintenance point

+ - run `python3 scripts/validate_okf.py knowledge --check-links`

+ - check for durable behavior, intent, architecture, policy, constraints,

+ terminology, or maintainer process that is missing from or contradicted by the

+ bundle; staleness is based on contradiction or missing coverage, not age alone

+ - ensure `knowledge/index.md` covers every concept and accurately classifies it

+ - remove or mark superseded obsolete concepts; update `knowledge/log.md` for

+ significant additions, removals, or changes

+ - keep `README.md`, `docs/`, and `AGENTS.md` aligned without linking public docs

+ into `knowledge/` or duplicating source-level detail

- 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/`.

+ `knowledge/`, `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

+ - check recently shipped features (see `git log` since the last tag) for a test that exercises them and a knowledge/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).