maintain

What this skill does

# 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

### 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", prefer the
one-command loop over walking each dimension by hand:

```bash
gbrain doctor --remediation-plan --json              # preview what would run
gbrain doctor --remediate --yes --target-score 90 --max-usd 5
```

`--remediation-plan` prints a dependency-ordered list (sync before extract,
embed after consolidate, etc.) with per-step `est_seconds` and `est_usd_cost`.
`--remediate` walks the plan, submitting each step as a Minion job, re-checking
score between every step. `--max-usd N` is a hard cost cap — submission refuses
when the plan would exceed the cap (prevents synthesize loops from burning
Anthropic credits unattended).

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),
the command bails with a list of what's missing rather than looping.

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 8-phase maintenance cycle:

```
lint -> backlinks -> sync -> synthesize -> extract -> patterns -> embed -> orphans
```

The two new phases consolidate yesterday's conversations into long-term memory:

**Synthesize phase:** reads transcripts from `dream.synthesize.session_corpus_dir`,
runs a cheap Haiku verdict (cached in `dream_verdicts`) to filter routine
ops sessions, then fans out one Sonnet subagent per worth-processing
transcript. Each subagent writes reflections (`wiki/personal/reflections/...`),
originals (`wiki/originals/ideas/...`), and people timeline entries. The
orchestrator collects the slugs from `subagent_tool_executions` (NOT
`pages.updated_at` — that would pick up unrelated writes) and reverse-renders
each new page from DB → markdown on disk.

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

**Quality bar (Iron Law for synthesis):**
1. Quote the user verbatim. Do not paraphrase memorable phrasings.
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.

**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 cheap Haiku significance filter (caches
verdicts) but skips the Sonnet synthesis pass. NOT zero LLM calls.

**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 8-phase 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.
Note: extracted entries improve structured queries (`gbrain timeline`), not vector search.

### Autopilot check
Verify autopilot is running:
```bash
gbrain autopilot --status
```
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.j