git:20260724.6548f64 to git:20260724.8351b7d

34 added, 163 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, 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 [`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)

- - 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 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

- ### Knowledge And Docs Alignment

- - 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,

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

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

+ evidence.

- ### Security And Threat Posture

+ [`knowledge/specs/maintenance.md`](../../../knowledge/specs/maintenance.md) owns the success bar and the

+ rationale behind each surface. This skill owns how to work a pass.

+ [`surfaces.md`](surfaces.md) holds the per-surface commands and heuristics —

+ open it for the surfaces your scope actually covers.

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

+ ## Scope

- - 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

+ Use the scope the user gave; otherwise state the one you inferred before

+ starting. Typical scopes: release readiness, CI health on `main`, `everruns-*`

+ dependency refresh, knowledge or docs drift, feature-completeness drift across

+ CLI / TUI / knowledge / README / tests, test gaps, code simplification, security

+ hygiene, performance of recently changed code, AGENTS / skills / command hygiene.

- ### Test And Runtime Confidence

+ ## Working a pass

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

+ A red CI on `main` outranks every other scope — fix it first, or open an issue

+ and report the pass **blocked**. Otherwise go highest-signal first: recent

+ diffs, failing checks, stale knowledge, outdated `everruns-*` versions.

- ## Common Evidence Commands

+ Prefer fixing over reporting. Fix what is small and local; for anything larger,

+ write a crisp finding and defer it to a GitHub issue naming the problem and its

+ user-visible impact — then put the issue number in the report. Skipping a

+ surface is fine; skipping it silently is not.

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

+ Keep each change PR-sized and independently reviewable. Do not fold a

+ simplification sweep into an unrelated fix. When a bug surfaces, prefer the

+ failing test before the fix.

- ## Deliverable

+ Validation matches the surfaces you touched — the

+ [checks in `AGENTS.md`](../../../AGENTS.md), plus a live-provider smoke through

+ Doppler when the pass touched runtime behavior. Do not declare release-ready

+ for surfaces you did not actually check.

- Report:

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

+ - scope covered, and what was intentionally skipped with a reason

+ - what was fixed, and what was found

+ - evidence gathered

+ - deferred findings with their GitHub issue numbers

+ - **blocked** if `main` CI is red and out of reach

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

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