maintain

# 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: ```bash 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 to get the dashboard. 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 extraction If link_count is 0 or low relative to page_count, run batch extraction: ```bash gbrain extract links --dir ~/brain ``` This scans all markdown files for entity references, See Also sections, and frontmatter fields, then creates typed links in the database. ### Timeline extraction If timeline_entry_count is 0, extract structured timeline from markdown: ```bash gbrain extract timeline --dir ~/brain ``` ### Dream cycle (v0.23): synthesize + patterns `gbrain dream` runs the full maintenance cycle (core phases shown; opt-in phases like atoms/concepts/drift slot in between): ``` lint -> backlinks -> sync -> synthesize -> extract -> patterns -> embed -> orphans ``` `fence_repair` runs right after `sync`, once per maintenance pass: it repairs the facts and takes fences sync held or pages store malformed (the same plan `gbrain repair fences` previews), for at most 300 s or a third of the job's remaining time, and resumes on the next run. `content_repair` runs right after it (#6377): the rest of the content-repair lane, today the `slug-conflicts` kind that removes a stray frontmatter `slug:` or records a recommended merge for a person (`gbrain repair content` previews both kinds), for at most 120 s or a third of the remaining time. Pause both with `gbrain config set fences.repair.enabled false`. The two new phases consolidate yesterday's conversations into long-term memory: **Synthesize phase (two-stage cascade):** reads transcripts from `dream.synthesize.session_corpus_dir`, then triages before it spends: a cheap utility-tier judge (`models.dream.triage`) scores every new file 0–1 for salience and pre-extracts candidate quotes + entities, cached in `dream_verdicts` with the judging model + prompt version (bounded per cycle by `dream.triage.max_ms`, default 5 min — deferred files retry next cycle, never silently rejected). A file passes the gate two ways: it scores at or above `dream.triage.threshold` (default 0.5), OR the **verified-segment rescue** fires — a score in `[dream.triage.rescue_floor, threshold)` still passes when at least `dream.triage.rescue_min_segments` (default 2; `0` disables) of the judge's own quoted segments verify as substrings of the transcript AND the content type is in `dream.triage.rescue_content_types` (default `mixed,reflection,idea,strategy,people` — never routine/technical). The rescue costs nothing (no extra LLM calls, it re-reads the cached verdict) and it is what recovers real signal buried in an otherwise mundane transcript. The whole gate is applied at READ time, so retuning the threshold or the rescue knobs re-gates with zero new LLM calls. Files that pass fan out one synthesis subagent per transcript chunk, each primed with the triage map. By default each child runs in oneshot mode (`dream.synthesize.mode`, default `oneshot`): ONE tool-less completion against a prompt carrying a pre-retrieved LINK CANDIDATES manifest (`dream.synthesize.link_manifest`, default on) and the write allow-list, validated end-to-end (slug fences, task shapes, wikilinks) before any page is written programmatically. A response that fails validation falls back to the classic agentic loop in the same job, where the `dream.synthesize.max_turns` cap (default 16) applies; revert dial: `gbrain config set dream.synthesize.mode agentic`. Each child writes reflections (`wiki/personal/reflections/...`) and originals (`wiki/originals/ideas/...`); people timeline entries are written only on the agentic path (fallback or `mode agentic`), where the child has the `add_timeline_entry` tool. The orchestrator collects the slugs from `subagent_tool_executions` (NOT `pages.updated_at` — that would pick up unrelated writes), runs the quote verify pass over them (below), and reverse-renders each new page from DB → markdown on disk. To re-apply the gate after retuning the threshold or the rescue knobs, or to drain a queued backlog, run `gbrain dream retriage --dry-run` (zero LLM calls, cached scores only) then `gbrain dream retriage --reconcile-queue`; `--force` re-judges everything from scratch. Retriage reads the SAME gate the cycle does, so a reconcile sweep never cancels a job the rescue admitted. **Claim verification (post-write, zero LLM):** after slug collection and before the reverse-write, `dream.synthesize.quote_verify` (default on) checks every page this phase's children wrote against the transcripts that produced it. Pages created this run are checked whole; pages that already existed are checked only on the sentences this run added. An exact quote is kept; a quote that differs only in whitespace, curly quotes, dashes, or case, or a close paraphrase inside one speaker's turn, is replaced with the verbatim transcript slice. A sentence is quarantined when a quote grounds nowhere or only across two speakers, when it attributes a real quote to the wrong speaker, or when it states a number or date the transcript lacks. Quarantined sentences leave the page body (and the timeline, facts and links derived from it) and are kept verbatim in frontmatter `unverified_claims`, which `get_page` shows but search, recall and think do not read. Grounded quotes record their source span and speaker in `grounding.quotes`. Nothing is ever fabricated. Telemetry lands in `details.synthesis.quote_verify`; the config key is the incident off switch. **Patterns phase:** runs after `extract` (so the graph state is fresh). Reads recent reflections within `dream.patterns.lookback_days` (default 30), runs a single Sonnet pass to surface recurring themes, and writes pattern pages to `wiki/personal/patterns/<theme>` when ≥`dream.patterns.min_evidence` (default 3) reflections support a pattern. A completed run records the newest reflection it consumed (`dream.patterns.last_evidence_ts`); until a reflection in the window is newer than that, re-runs skip with `no_new_evidence` instead of paying for another model pass — `gbrain dream --phase patterns --once` forces one. **Quality bar (Iron Law for synthesis):** 1. Quote the user verbatim. Quotation marks are ONLY for spans reproducible EXACTLY from the transcript — if you cannot reproduce a span exactly, paraphrase it WITHOUT quotation marks. Do not paraphrase memorable phrasings you can quote exactly. (The quote verify pass enforces this mechanically after the write.) 2. Cross-reference compulsively: every new page MUST have at least one wikilink. 3. Slug discipline: lowercase alphanumeric and hyphens only. NO underscores, NO file extensions. 4. Edited transcripts produce NEW slugs (content-hash suffix changes) — never silently overwrite. 5. Preserve concrete facts: carry the specific numbers, dates, dollar amounts, names, and who-decided-what of the salient content, exactly as the transcript states them. Do not pad with routine logistics. 6. Ground every claim in the transcript. Attribute speculation as speculation, and never state a completion state or outcome the transcript does not show. **Trust boundary (`allowed_slug_prefixes`):** the synthesis subagent runs with an explicit allow-list of write paths sourced from `_brain-filing-rules.json`'s `dream_synthesize_paths.globs`. Even on prompt-injection success, the subagent cannot write outside that list. Trust comes from PROTECTED_JOB_NAMES — MCP cannot submit subagent jobs at all. Editing the JSON is the only way to add a new directory the synthesizer can write to. **Idempotency + privacy:** transcripts are keyed by `(file_path, content_hash)`, so re-running on the same content is a no-op. `dream.synthesize.exclude_patterns` (default `["medical", "therapy"]`) filters out transcripts before any LLM call. Each entry is auto-wrapped as a word-boundary regex (e.g. `medical` matches "medical advice" but NOT "comedical"). Power users may pass full regex. **Cooldown:** the cycle's spend cap. `dream.synthesize.cooldown_hours` (default 12) means at most ~2 synthesize runs per day under autopilot. The completion timestamp is stored in `dream.synthesize.last_completion_ts` and is written ONLY on successful runs (not on skipped/failed). Explicit `--input` / `--date` / `--from` / `--to` invocations bypass cooldown. **`--dry-run` semantics:** runs the scored triage pass (judges + caches verdicts for new files) but skips the synthesis subagents. NOT zero LLM calls — for a zero-call preview from cached scores use `gbrain dream retriage --dry-run` instead. **Configure synthesize on a fresh brain:** ```bash gbrain config set dream.synthesize.session_corpus_dir /path/to/transcripts gbrain config set dream.synthesize.enabled true gbrain dream --phase synthesize --dry-run --json # preview gbrain dream # full cycle ``` **Invocation patterns:** ```bash gbrain dream # full cycle gbrain dream --phase synthesize # just synthesize gbrain dream --phase patterns # just patterns gbrain dream --input ~/transcripts/2026-04-25.txt # ad-hoc one transcript gbrain dream --from 2026-04-01 --to 2026-04-25 # backfill range gbrain dream --json # CycleReport JSON ``` **Auto-commit deferred to v1.1:** v1 writes files to `brain_dir` but does NOT `git add` / `commit` / `push`. Either commit yourself or let `gbrain autopilot` handle it. Parses `- **YYYY-MM-DD** | Source — Summary` and `### YYYY-MM-DD — Title` formats. The `Source — Summary` dash may be an em dash, an en dash or a spaced hyphen (` - `); a colon (`Source: Summary`) is prose, so the row keeps `source: markdown` and the whole text as its summary. Note: extracted entries improve structured queries (`gbrain timeline`), not vector search. ### Autopilot check Verify autopilot is running: ```bash gbrain autopilot --status ``` The exit code is trustworthy for gating: 0 fresh (or nothing installed), 1 needs attention (stale heartbeat, never ran, or paused by a migration), 2 the daemon disabled itself (its repo path vanished). `--json` emits the full report (`state`, `heartbeat_age_seconds`, `paused_reason`, `disabled_reason`). Status reads only the filesystem, so it works even when the database is down. If not running, install it: ```bash gbrain autopilot --install --repo ~/brain ``` Autopilot runs sync, extract, and embed in a continuous loop with adaptive scheduling. In v0.11.1+, autopilot dispatches each cycle as a single `autopilot-cycle` Minion job and supervises the worker child — one install step gives you sync + extract + embed + backlinks + durable job processing. ### Fix a half-migrated install A v0.11.0 install where the migration skill never fired leaves Minions partially set up: schema is applied, but `~/.gbrain/preferences.json` doesn't exist, autopilot runs inline, host manifests still reference `agentTurn`. Repair: ```bash # Check migration status gbrain apply-migrations --list # Apply pending migrations (idempotent; safe on healthy installs) gbrain apply-migrations --yes # If host-specific handlers are flagged in ~/.gbrain/migrations/pending-host-work.jsonl: # walk them per skills/migrations/v0.11.0.md + docs/guides/plugin-handlers.md, # ship handler registrations in the host repo, then re-run apply-migrations. ``` Full troubleshooting guide: `docs/guides/minions-fix.md`. ### Back-link enforcement Check that the back-linking iron law is being followed: - For each recently updated page, check if entities mentioned in it have corresponding back-links FROM those entity pages - A mention without a back-link is a broken brain - Fix: add the missing back-link to the entity's Timeline or See Also section - Format: `- **YYYY-MM-DD** | Referenced in [page title](path) -- brief context` ### Filing rule violations Check for common misfiling patterns (see `skills/_brain-filing-rules.md`): - Content with clear primary subjects filed in `sources/` instead of the appropriate directory (people/, companies/, concepts/, etc.) - Use gbrain search to find pages in `sources/` that reference specific people, companies, or concepts -- these may be misfiled - Flag misfiled pages for review or re-filing ### Citation audit Spot-check pages for missing `[Source: ...]` citations: - Read 5-10 recently updated pages - Check that compiled truth (above the line) has inline citations - Check that timeline entries have source attribution - Flag pages where facts appear without provenance ### Tag consistency Inconsistent tagging (e.g., "vc" vs "venture-capital", "ai" vs "artificial-intelligence"). - Standardize to the most common variant using gbrain tag operations ### Graph population (v0.10.3+) The `links` and `timeline_entries` tables are the structured graph layer. Populate them periodically or after major imports: - `gbrain extract links --source db` — backfill structured links by walking pages from the engine. Reads `[Name](people/slug)` / `[Name](companies/slug)` references and infers relationship types (`attended`, `works_at`, `invested_in`, `founded`, `advises`, `mentions`, `source`). Idempotent. Use `--source fs --dir <brain>` if you have a markdown checkout to walk instead. - `gbrain extract timeline --source db` — backfill structured timeline entries. Parses `- **YYYY-MM-DD** | summary` lines from page content. Idempotent (DB UNIQUE constraint). - `gbrain extract all --source db` — both in one run. - `gbrain graph-query <slug> --depth 2` — verify connectivity (use any well-known entity slug as a probe). - `gbrain stats` — verify `link_count > 0` and `timeline_entry_count > 0` after extraction. - `gbrain health` — review `link_coverage` and `timeline_coverage` percentages on entity pages (person/company). Below 50% means more extraction is needed. On brains with very few entity pages these report "too few to grade" (`null` in JSON, with `entity_page_count` carrying the denominator) instead of a misleading 0%/100% — grow the entity set before acting on coverage. Available link types (use with `gbrain graph-query --type`): `attended`, `works_at`, `invested_in`, `founded`, `advises`, `mentions`, `source`. Going forward, every `gbrain put` call auto-creates and reconciles links via the auto-link post-hook (default on; disable: `gbrain config set auto_link false`). So link-extract is mostly a one-time backfill. timeline-extract should be re-run after bulk imports or content edits that add new dated entries. ### Feature adoption check (weekly) ```bash gbrain features --json # scan for underused features + recommendations ``` Run weekly alongside lint. Surfaces missing embeddings, unused integrations, and configuration improvements. ### Embedding freshness Chunks without an embedding yet (`--stale` selects exactly those). Embedding calls the configured provider, which bills per token, so this is paid work that needs the user's approval first: 1. Preview with no provider calls: `gbrain embed --stale --dry-run`. 2. Relay the chunk count and cost estimate to the user and wait for an answer. 3. Only after they agree, run `gbrain embed --stale --yes --max-usd <cap>` with the cap they approved. Without approval the command stops with exit 3 and an `[AGENT]` block asking