kb-sleep-maintenance - SKILL.md Agent Skill

name: kb-sleep-maintenance description: Run the repository-managed local KB Sleep maintenance pass. Use only when a user or automation explicitly asks for KB Sleep, sleep maintenance, local KB consolidation, or the scheduled KB Sleep automation; do not use for ordinary task preflight or active-task KB writes.

KB Sleep Maintenance

Run one dedicated Sleep maintenance pass for this predictive KB repository.

Sleep is the experience-library editor, not a candidate factory. Optimize for accuracy, clarity, future usability, and logical route structure, not for fewer cards or more generated candidates.

Authority

Work from the repository root. Treat these files as authoritative and read them before stateful maintenance:

PROJECT_SPEC.md
docs/maintenance_agent_worldview.md
docs/maintenance_runbook.md
.agents/skills/local-kb-retrieve/MAINTENANCE_PROMPT.md

Current user instructions still override repository files.

Execution Contract

Before the first stateful command, run python .agents/skills/local-kb-retrieve/scripts/kb_lane_status.py --lane kb-sleep --status running --wait-clear --poll-seconds 300 --json. If another core maintenance lane is running, wait and recheck every 5 minutes until the lane is free; do not skip merely because another lane is active.
Write a visible execution plan before the first stateful command after the lane guard, with checkpoint statuses.
Read the shared maintenance-agent worldview and use it as the judgment model for accuracy, clarity, usefulness, evidence strength, and human-reviewable output quality.
Run the sleep self-preflight search against system/knowledge-library/maintenance.
Inspect taxonomy, route gaps, route navigation when needed, and proposal-mode consolidation output.
Track the current maintenance run id from the consolidation output or chosen --run-id; reuse that same run id in the final lane status completion command.
Before choosing any apply lane, summarize high-volume proposal output as a compact editorial sample pack: action counts, apply eligibility, top route clusters, duplicate candidate clusters, strong examples, weak/noisy examples, Architect-only items, Dream-only items, low-risk navigation examples, and hub-card review examples. Use that map before deep-reading large raw JSON.
Treat candidate backlog as a maintenance object: decide what should be kept, rewritten, merged, rejected, watched, or left proposal-only before adding more candidates.
Treat mechanical apply eligibility as capability only. Do not run a broad apply mode over every eligible action; keep the pass proposal-only unless a compact reviewed set of action keys is explicitly selected.
Run the mandatory similar-card merge checkpoint. Inspect cards surfaced by maintenance output for overlapping scenario, action, prediction, route, or evidence. Decide whether to merge, propose a merge, or skip application with a concrete reason.
Run the mandatory overloaded-card split checkpoint. Inspect recurrent, broad, or split_review_suggestion cards and decide whether each one is still a hub card, should move toward a split proposal, or should skip application with a concrete reason.
Run the organization Skill bundle consolidation checkpoint. For imported read-only organization Skills, group by bundle_id, keep only the latest approved version by version_time, preserve source-card references, and keep all local cards pointing at the same bundle_id.
Do not skip the merge, split, or Skill bundle consolidation checkpoint itself. It is acceptable to skip applying a merge, split, or Skill replacement when evidence, safety, tooling, or scope is insufficient, but the inspection and recorded decision must still happen.
Prefer functional, reusable domain paths over project-name route roots when reviewing candidates.
Continue through every safe checkpoint instead of stopping after a short proposal.
Apply only clearly eligible low-risk lanes supported by current tooling: new-candidates, related-cards, cross-index, AI-authored semantic-review, and AI-authored zh-CN i18n. Tool eligibility is not editorial approval; compare the whole eligible set with the editorial map before applying.
Do not create new candidates merely because the tooling can; use new-candidates only when backlog triage shows the scaffold would improve future retrieval.
If an apply mode contains both approved and unapproved actions, use selected action keys instead of skipping the whole lane: --action-key <approved-action-key> may be repeated. Skip only when the approved set cannot be named by exact action key.
Limit semantic-review to at most 3 trusted-card modifications per run.
Run a canonical-interface checkpoint before translation apply: top-level card fields, route values, CLI machine JSON, automation payload keys, and installer checks remain canonical machine surfaces; Chinese stays in i18n.zh-CN, route display labels, and UI view models.
Run exactly one final AI-authored zh-CN display completion checkpoint after candidate/card creation, semantic text changes, and route review are done. This single checkpoint covers card display fields and route/path display labels, writes missing route labels through the i18n plan, and replaces separate mid-run translation cleanup.
Keep taxonomy rewrites proposal-only unless current tooling cleanly supports the exact change.
Inspect rollback artifacts when needed, including history-events, related-card-entries, cross-index-entries, and semantic-review-entries when present.
Attempt supported low-risk repairs and rerun the relevant validation when a command exposes a fixable issue.
Run a final sleep postflight check.
Append one structured maintenance observation when the pass exposed a reusable lesson, route gap, card weakness, merge signal, split signal, Skill bundle update, interface-boundary gap, or process hazard.
Run python .agents/skills/local-kb-retrieve/scripts/kb_lane_status.py --lane kb-sleep --status completed --run-id --json.
Stop after that final observation. Do not immediately consolidate the observation just written.

Report

Report the run id, checkpoint status, self-preflight entries, what became more accurate, clearer, or easier to retrieve, observation counts reviewed, candidates created or deliberately not created, weak/noisy material rejected or kept history-only, route adjustments or concerns, similar-card merge checkpoint decisions, overloaded-card split checkpoint decisions, organization Skill bundle consolidation decisions, semantic-review decisions applied or skipped, canonical-interface checkpoint status, final zh-CN display completion status for cards and routes, translations updated or still missing, validations run, repaired or proposal-only issues, maintenance decisions, postflight observation status, undeclared taxonomy gaps, hub-vs-overloaded card reviews, and next proposal-only targets.

Purpose

Bind each kb run to the declared integration mode, evidence, blockers, residual_risk, and claim_boundary.

Entrypoint Scope

Covers kb-sleep-maintenance plus explicitly routed local materials; no unrelated repos, private files, external services, publication, or release claims unless requested and routed.

Local Material Routing

Use workspace, skill directory, user files, or configured project paths; keep private machine paths local and public instructions portable.

Entrypoint Acceptance Map

Use SkillGuard as the runtime contract executor attached to the native route/check owner: Predictive KB launcher, local KB records, and KB maintenance workflow. It enforces contract gates through that native owner before progress or closure; duplicate SkillGuard-owned execution paths are invalid. Declared gates/routes: recall or maintenance, evidence update, validation, closure.

Use When

Use when the request matches kb-sleep-maintenance and needs this governed workflow, materials, checks, or handoff behavior.

Do Not Use When

Do not use outside the domain, without required materials, when a more specific skill owns the work, or for tiny direct answers.

Required Workflow

Select the target-owned native route/check surface, run the SkillGuard contract gates around the native workflow, collect evidence, run checks, fix failures, then report.

Hard Gates

Do not skip phases, do not replace required evidence with prose, do not treat stale reports as current, do not weaken validation to pass, and do not claim completion when blockers remain.

Output Requirements

Report evidence, failures, blockers, skipped_checks with reasons, residual_risk, and claim_boundary; distinguish checked, unchecked, blocked, and uncertain.

SkillGuard Maintenance

Keep .skillguard contracts, checks, evidence, and ledger current; rerun SkillGuard after entrypoint, route, evidence, or closure changes.