khaos-brain-update - SKILL.md Agent Skill

name: khaos-brain-update description: Apply a clean repository-managed Khaos Brain software update. Use only when a user, UI request, or Architect pass explicitly authorizes an update; this recovery-oriented skill force-closes the desktop UI, preserves local KB state, fast-forwards source code, and refreshes installer-managed Codex integration.

Khaos Brain Update

Apply one clean software update for this Khaos Brain repository.

This Skill is intentionally narrow. It updates the software and Codex-side integration; it does not decide whether an update is wanted. Version discovery, user intent, UI state display, and scheduling belong to KB Architect or the UI.

Recovery Boundary

Do not require KB preflight, desktop settings reads, organization repository reads, or card retrieval before applying this Skill. The update path must still work when the local KB, desktop settings, UI, or organization cache is broken.

If a normal healthy Architect pass invoked this Skill, Architect may already have done KB preflight. This Skill itself must not make the update depend on those higher-level systems.

Preserve

Treat these as local state that must survive an update:

.local/, including khaos_brain_desktop_settings.json, organization caches, exchange hash ledgers, import records, screenshots, and install identity files.
kb/private/, kb/history/, kb/candidates/, kb/outbox/, and other ignored local KB state.
User-created untracked files unless the user explicitly asked to remove them.
Installed organization Skills, downloaded organization Skill bundles, and local Skill review state.
$CODEX_HOME/predictive-kb/install.json and user-owned Codex configuration outside the repository-managed blocks.

The installer may refresh repository-managed global skills, repository-managed automations, and repository-managed global AGENTS blocks.

Apply Contract

Work from the repository root. Confirm it contains PROJECT_SPEC.md, scripts/install_codex_kb.py, and .agents/skills/khaos-brain-update/SKILL.md.
Mark the UI-blocking state before changing files: python scripts/khaos_brain_update.py --mark upgrading --json
Force-close Khaos Brain desktop UI processes before changing files. Do not wait for a graceful close. On Windows, target only Khaos Brain UI processes, such as Khaos Brain.exe, KhaosBrain.exe, windows titled Khaos Brain, or Python command lines running kb_desktop.py or open_khaos_brain_ui.py. Do not broadly kill unrelated python, node, electron, or codex processes.
Inspect tracked working-tree state with Git. If tracked source files are dirty and the user did not explicitly authorize updating over local source edits, stop before fetching or pulling and report the dirty paths. Ignored private KB state is not a blocker.
Fetch from the configured upstream with tags and pruning.
Update only by fast-forward. Prefer the current branch's upstream; if no upstream exists and the repository is on main, use origin/main. Do not run git reset --hard, force checkout, rebase, or tag moves.
Run python scripts/install_codex_kb.py --json.
Run python scripts/install_codex_kb.py --check --json.
If the desktop package or shortcut changed and the installer exposes a supported refresh path, use that supported path. Do not invent a packaging step during update.
Mark successful completion: python scripts/khaos_brain_update.py --mark current --json

Failure Rules

If the fast-forward fails because local source changes exist, the branch diverged, or the remote is unavailable, stop cleanly and leave local state untouched.
If the installer or install check fails after source update, mark failure with python scripts/khaos_brain_update.py --mark failed --error "" --json, report the exact failing command, and leave rollback to a separate explicit recovery action.
Do not delete local KB cards, organization caches, hash ledgers, Skill bundles, or settings as part of update failure handling.

Report

Report the previous revision, target revision, whether the UI was force-closed, Git update result, installer result, install-check result, update-state path if written, and any remaining manual action.

Purpose

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

Entrypoint Scope

Covers khaos-brain-update 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 khaos-brain-update 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.