/maintain

name: maintain
version: 1.1.0
upstream: maintain@fc834ee
description: |
  Brain health checks: back-link enforcement, citation audit, filing validation,
  stale info detection, orphan pages, and benchmarks. Use when asked to check
  brain health, run maintenance, or audit quality.
triggers:
  - "brain health"
  - "check backlinks"
  - "maintenance"
  - "orphan pages"
  - "stale pages"
  - "extract links"
  - "build link graph"
  - "populate timeline"
  - "populate links"
  - "backfill graph"
  - "extract timeline entries"
  - "retriage the backlog"
  - "re-score the triage"
  - "run dream"
  - "process today's session"
  - "process yesterday's transcripts"
  - "synthesize my conversations"
  - "what patterns did you see"
  - "did the dream cycle run"
  - "consolidate yesterday's conversations"
tools:
  - get_health
  - get_brain_health
  - get_page
  - put_page
  - list_pages
  - get_backlinks
  - add_link
  - search
mutating: true

Maintain Skill

Periodic brain health checks and cleanup.

Contract

This skill guarantees:

• All health dimensions are checked (stale, orphan, dead links, cross-refs, backlinks, citations, filing, tags)
• Each issue found has a specific fix action
• Back-link iron law is enforced
• Citation format is validated against the standard
• Results are reported with counts per dimension

Phases

Ownership failures are an inspection boundary

Routine maintenance, startup checks, `doctor --fix`, and a request to "fix what's broken" do not authorize writer topology changes. On `owner_unavailable` or a writer coordination refusal, inspect `gbrain sources writer status --brain <id> --json` on the selected host first and report the owner, epoch, enabled state and blocked recovery to the operator. Do not claim a checkout, activate managed mode, transfer an owner, replace identities, or remove ownership markers as a repair. When the status reads `enabled: false` and the refusal says `unbound_source`, the brain is in classic mode on purpose: report that writes go through the checkout (file, commit, `gbrain sync`) and leave it classic. Deliberate administration requires a separately approved topology change and the action-specific intent plus reviewed state precondition described in `docs/architecture/topologies.md`. Neither a TTY nor `--yes` nor `--confirm-quiesced` substitutes for that decision. Remote credentials remain ineligible for local writer administration.

Autonomous path (v0.36.4.0) — when you want to reach a target score

If the user asks "get my brain to 90/100" or "fix what's broken", preview first and ask before applying anything:

gbrain doctor --remediation-plan --json              # preview: job steps + repair steps
# Show the user the repair steps (each "requires user agreement") and the cost.
# Only after the user agrees (plan_hash from the preview binds the approval):
gbrain doctor --remediate --yes --include-repairs --expect <plan_hash> --target-score 90 --max-usd 5

`--remediation-plan` prints a dependency-ordered list of job steps (sync before extract, embed after consolidate, etc.) with per-step `est_seconds` and `est_usd_cost`, and, independent of the score target, the PROTECTED repair steps for every `gbrain repair` kind with pending items. Each step carries the exact command that applies it, and the plan ends with one combined command. `--remediate` runs the repair steps only with `--include-repairs` (the user's agreement; without it they are listed as skipped), then walks the job plan, submitting each step as a Minion job and re-checking score between steps. `--max-usd N` is a cumulative cost cap across the run and every `--resume`: a paid step that would exceed it is not started, free steps still run, and the run stops with a resume command that keeps the cap and the agreement.

When the target score is unreachable for the brain (empty brain with no entity pages → `graph_coverage` caps at 70; unconfigured embedding key → caps at 60), job steps stop with a list of what's missing rather than looping; included repair steps still run. `--json` classifies each finding `cleared`, `pending`, `consent_required`, `operator_required` (follow its instruction) or `unsupported` (report it; nothing clears it yet). After an upgrade, follow the recipe in `docs/guides/repair.md#recover-after-upgrading-to-this-release`.

Use the per-dimension walk below (Phase 2 onward) when:

• The user explicitly asks for a dimension-by-dimension audit
• You're investigating why score is stuck below `--remediate`'s ceiling
• A specific dimension needs manual judgment that the auto path skips

Manual path

1. **Run health check.** Check gbrain health (`get_health`) to get the dashboard. `get_health` needs admin scope; without it, call `get_brain_health` (read scope), which returns bands only (write capacity, write failures, ghost pages, unsearchable chunks), and skip the dimensions it cannot answer: stale pages, orphan pages, dead links, embed coverage, link and timeline counts and the brain score. Name the skipped dimensions in the report and ask for an admin token, or for `gbrain doctor --json` on the brain host, to cover them. 2. **Check each dimension:**

Stale pages

Pages where compiled_truth is older than the latest timeline entry. The assessment hasn't been updated to reflect recent evidence.

• Check the health output for stale page count
• For each stale page: read the page from gbrain, review timeline, determine if compiled_truth needs rewriting

Orphan pages

Pages with zero inbound links. Nobody references them.

• Review orphans: are they genuinely isolated or just missing links?
• Add links in gbrain from related pages or flag for deletion

Dead links

Links pointing to pages that don't exist.

• Remove dead links in gbrain

Missing cross-references

Pages that mention entity names but don't have formal links.

• Read compiled_truth from gbrain, extract entity mentions, create links in gbrain

Link graph extractio