---
type: Process Specification
title: Maintenance Specification
description: Defines the success criteria for repository maintenance and release readiness.
---
# Maintenance Specification
## Abstract
This specification defines goal-oriented maintenance for yolop. Maintenance improves release readiness and repo health with evidence, not by mechanically executing a fixed checklist.
The canonical agent workflow lives in [`.agents/skills/maintenance/SKILL.md`](../../.agents/skills/maintenance/SKILL.md). That skill is user-invocable so maintenance can be requested directly as `/maintenance`.
## Design Goals
1. Make the maintenance scope explicit.
2. Improve the repo in concrete ways or produce crisp findings with evidence.
3. Match validation depth to the actual risk surface.
4. Keep release claims honest.
5. Detect drift between yolop and its upstream source (`examples/coding-cli` in `everruns/everruns`).
6. Detect feature-completeness drift: features that look shipped on one surface
(CLI flags, TUI behavior, specs, README, docs, tests, bundled skills) but are
missing or stale on another.
7. Reduce accidental complexity: remove over-abstraction, dead code, and premature generalization the codebase no longer earns.
## Ownership Boundary
- This spec owns the maintenance intent, constraints, and success bar.
- The skill owns the execution workflow, heuristics, and example commands.
## Constraints
- Maintenance is risk-proportional, not sweep-proportional.
- The selected scope must be explained, including what was skipped and why.
- If maintenance changes code or behavior, affected artifacts must stay in sync:
`README.md`, `docs/`, `AGENTS.md`, `knowledge/specs/`.
- Maintenance prefers concrete fixes over ceremonial audits when a safe local fix exists.
- Dependency upgrades against external registries should respect a short release-age floor (≥1 day for patch, ≥7 days for minor/major) to avoid landing same-day yanks.
## CI Health Gate
GitHub Actions on `main` is the CI source of truth. The latest run on `main`
must be green before a maintenance pass is reported complete:
- A red `main` is the first maintenance item, ahead of any other scope.
- If the pass cannot fix the failure, it must open a tracked issue and report
the pass as **blocked**, not complete.
## Deferred Findings
Findings too large to fix inline (multi-file refactors, upgrades needing
non-trivial rework) are deferred, not dropped:
- each deferred finding becomes a GitHub issue with scope and reproduction
- the issue numbers appear in the maintenance report
Deferred items are not failures. Untracked ones are.
## Feature Completeness Drift
A feature is not release-ready merely because one surface exists. Yolop's
surfaces are the CLI flags, the presentation model, the TUI behavior, `--print`
output, ACP output, `knowledge/specs/`, `README.md`, `docs/`, the test suite, and bundled
system skills. Maintenance should catch:
- flags or behavior present in `src/` but absent from `README.md`, `docs/`, or
`knowledge/specs/`
- specs or README describing behavior the binary no longer has
- shipped features with no test exercising them
- user-visible transcript/status behavior tested only through terminal buffers
instead of the terminal-independent presentation model
The outcome is either a small fix that reconnects the surfaces or a crisp
finding naming the missing surface and its user-visible impact — not a
generic "tech debt" note.
## Dependency Discipline
The `everruns-*` family is yolop's single most consequential dependency vector:
- `everruns-runtime`
- `everruns-core`
- `everruns-openai`
- `everruns-anthropic`
- `everruns-integrations-duckduckgo`
These crates ship together from one upstream workspace and are designed to be used at the same version. Yolop pins them at a single minor version. Mixing minor versions across the family is a soft API break and is not allowed without an explicit reason recorded in the PR.
Beyond the everruns family, dependency hygiene means:
- no known CVEs in the tree (`cargo audit` when available, plus the repo's Dependabot alerts)
- duplicate transitive versions reviewed (`cargo tree --duplicates`) — fix or note why unfixable
- no unused direct dependencies; prefer narrow sub-crates over umbrella crates when only a slice is used
## Upstream Mirror
Yolop began as `examples/coding-cli` in `everruns/everruns`. Maintenance should periodically:
- compare `src/` to the latest upstream example
- pull non-everruns-specific improvements (UI tweaks, bug fixes, capability wiring)
- leave behind anything tied to internal everruns paths or specs
- note material divergence as a comment near the code, not a separate doc
When upstream changes the public runtime API, bump the `everruns-*` versions in `Cargo.toml` together and reconcile any compile errors before the new feature lands.
## Release Readiness Standard
Before tagging a release:
- the `everruns-*` family is on the latest released minor
- `cargo build --release` succeeds and the resulting binary starts (`./target/release/yolop --help`)
- `cargo test --all-features` is green
- the live-provider integration test passes under Doppler
- the README's feature list, flag table, and provider env-var table match the source
## Security And Threat Posture
Yolop uses native containment for arbitrary shell commands by default. The
remaining threat surface is concentrated:
- **Filesystem** — structured file tools still use the rooted real-disk broker
and protected-path checks. Maintenance must verify those mounts and checks
remain wired.
- **Shell** — arbitrary commands spawn through the configured sandbox provider.
Maintenance must run the workspace-write, outside-write, network-denial,
worktree-switch, timeout, and output-cap tests on macOS and Linux.
- **Session log** — JSONL session logs contain prompts, tool arguments, and tool output. They must be created with `0o600` on Unix.
- **API keys** — provider keys must only be read from process env. They must never be written to the session log or echoed to tracing output.
[`sandboxing.md`](./sandboxing.md) defines the implemented boundary and its known limitations.
## Code Simplification And De-Abstraction
Complexity accretes: an abstraction added for a second caller that never
arrived, a trait with one impl, a config knob nobody sets. A deep maintenance
pass treats removing that complexity as real work, not a side effect. The bias
is toward deletion — the healthiest passes often remove more code than they add.
Maintenance should look for and collapse:
- single-use abstractions (one-impl traits, forwarding wrappers, single-instantiation generics, builders for trivial structs) — unless the seam is load-bearing
- premature generalization: flexibility shaped for hypothetical futures, not current callers
- indirection with no payoff: helpers that only rename a stdlib call, modules that re-export one item, always-default knobs
- under-abstraction: the same block pasted in several places, where a shared helper genuinely reduces total code
- deep nesting and long match arms that a flatten or extraction makes legible
- names that hide intent
Constraints:
- A simplification must preserve behavior. It is verified by build, clippy, and
the test suite — a behavior change disguised as cleanup is a regression.
- Keep simplifications small and independently reviewable; do not fold a
de-abstraction sweep into an unrelated change.
- Removing a public item from a published crate (`yolop-yep`, `tuika`) is a
breaking change and must be called out, not slipped in.
- A simplification too large to land inline (a cross-cutting abstraction with
many call sites) is deferred to a tracked issue naming the abstraction and why
it no longer pays its way — same discipline as any other deferred finding.
This is the inverse of premature abstraction, not an argument against all
abstraction: an abstraction that carries real, current weight stays.
## Spec Hygiene
Specs preserve design intent, rationale, and constraints — not implementation details readable from code. Maintenance should:
- replace duplicated struct/enum/field tables with links to source
- replace exhaustive feature-flag or capability lists with links to source
- keep the "why" and constraints; link to code for the "what"
## Related
- [`.agents/skills/maintenance/SKILL.md`](../../.agents/skills/maintenance/SKILL.md)
- [`knowledge/specs/documentation.md`](./documentation.md)
- [`knowledge/specs/shipping.md`](./shipping.md)