medic

source	shipped
name	medic
description	Colony health diagnostics and repair — healthy state specifications for all colony data files, failure modes, and remedies
type	colony
domains	["health","diagnostics","repair","data-integrity","validation"]
agent_roles	["builder","watcher","medic"]
priority	normal
version	1.0

Medic: Colony Data Health Reference

Purpose

This skill defines what healthy colony data looks like. Workers should reference this when modifying colony state files or diagnosing colony issues. The Medic worker (aether medic) uses these rules to scan for problems and repair them.

COLONY_STATE.json Healthy State

Schema

Field	Type	Required	Valid Values
version	string	yes	"3.0"
goal	*string	yes	non-empty string
state	State	yes	IDLE, READY, EXECUTING, BUILT, COMPLETED
scope	ColonyScope	yes	"project", "meta"
current_phase	int	yes	>= 0
colony_version	int	no	starts at 1
session_id	*string	no	format: {unix}_{hex}
parallel_mode	ParallelMode	no	"in-repo", "worktree"
paused	bool	no	only valid when state is READY
milestone	string	no	milestone name
worktrees	[]WorktreeEntry	no	each has status field
signals	[]Signal	deprecated	should be empty — migrated to pheromones.json
events	[]string	no	pipe-delimited: timestamp|type|source|description
plan	Plan	no	phases with PhaseStatus and tasks
memory	Memory	no	instincts, learnings, errors

State Machine

Legal transitions (from pkg/colony/colony.go:490):

• IDLE → READY
• READY → EXECUTING, COMPLETED
• EXECUTING → BUILT, COMPLETED
• BUILT → READY, COMPLETED
• COMPLETED → IDLE

Consistency Rules

• If state is EXECUTING, current_phase must be > 0
• If paused is true, state should be READY
• If parallel_mode is "worktree", worktrees array should be maintained
• Events entries must be pipe-delimited with at least 2 segments

Common Failures

Failure	Severity	Detection
Missing or empty goal	critical	goal field nil or empty
Invalid state value	critical	not in IDLE/READY/EXECUTING/BUILT/COMPLETED
EXECUTING with phase 0	warning	state mismatch
Paused but not READY	warning	flag/state conflict
Deprecated signals present	warning	signals array non-empty
Orphaned worktrees	warning	status="orphaned" entries
Invalid parallel_mode	warning	not "in-repo" or "worktree"
Malformed event entries	warning	missing pipe delimiters
Legacy state strings	warning	PAUSED/PLANNED/SEALED/ENTOMBED

Remedies

• Legacy states: Auto-normalized by normalizeLegacyColonyState() in cmd/state_load.go
• Orphaned worktrees: Remove entries with status="orphaned" (verify git worktree doesn't exist first)
• Deprecated signals: Migrate to pheromones.json, clear signals array
• EXECUTING without phase: Reset to READY
• Invalid parallel_mode: Report for manual correction

pheromones.json Healthy State

Schema

Field	Type	Required	Valid Values
id	string	yes	unique identifier
type	PheromoneType	yes	FOCUS, REDIRECT, FEEDBACK
active	bool	yes	true/false
content	json.RawMessage	yes	valid JSON (supports nested objects)
created_at	string	yes	parseable timestamp
expires_at	*string	no	parseable timestamp
content_hash	*string	no	SHA-256 for dedup
strength	*float64	no	0.0-1.0
priority	string	no	"normal", "high", "low"

Content Rules

• Content is json.RawMessage, NOT a plain string
• Supports nested objects like {"text": "..."}
• Max 500 characters (enforced by SanitizeSignalContent())
• No XML structural tags, no prompt injection patterns, no shell injection

Common Failures

Failure	Severity	Detection
Missing signal ID	warning	id field empty
Invalid signal type	warning	not FOCUS/REDIRECT/FEEDBACK
Expired but still active	warning	expires_at past, active=true
Duplicate content hash	warning	same hash with different IDs
Invalid content JSON	critical	content not valid JSON

Remedies

• Expired signals: Set active=false, set archived_at timestamp
• Missing IDs: Generate sig_{unix}_{4hex}
• Invalid types: Default to FOCUS (safest)
• Duplicate hashes: Keep most recent, archive older

session.json Healthy State

Schema

Field	Type	Required	Notes
session_id	string	yes	unique session identifier
started_at	string	yes	parseable timestamp
colony_goal	string	yes	should match COLONY_STATE goal
current_phase	int	yes	should match COLONY_STATE current_phase
current_milestone	string	no	milestone name
suggested_next	string	no	next recommended command
context_cleared	bool	no	whether context was cleared
baseline_commit	string	no	git commit hash
last_command	string	no	last command run
last_command_at	string	no	timestamp of last command
active_todos	[]string	no	active todo items
summary	string	no	session summary

Cross-Reference Rules

• current_phase must match COLONY_STATE.json current_phase
• colony_goal must match COLONY_STATE.json goal

Staleness Thresholds

• Last activity >7 days: warning
• Last activity >30 days: critical

Common Failures

Failure	Severity	Detection
Phase mismatch with COLONY_STATE	warning	values differ
Goal mismatch with COLONY_STATE	warning	strings differ
Missing session_id	warning	field empty
Invalid started_at	warning	not parseable
Stale session	warning/critical	>7d or >30d

Remedies

• Phase/goal mismatch: Sync from COLONY_STATE.json
• Stale session: User should run /ant-resume to refresh

Data Files Healthy State

midden/midden.json

• Location: .aether/data/midden/midden.json (subdirectory — different from other data files)
• Structure: MiddenFile with archived_signals, entries, spawn_metrics
• Common failures: corrupted JSON
• Remedy: JSON recovery with --force

instincts.json

• Structure: InstinctsFile with entries (trigger, action, domain, trust_score, confidence, provenance)
• Note: Two instinct representations exist — simple Instinct in ColonyState.Memory and rich InstinctEntry here
• Common failures: corrupted JSON
• Remedy: JSON recovery with --force

learning-observations.json

• Structure: LearningFile with observations (content_hash, content, wisdom_type, trust_score)
• Common failures: corrupted JSON
• Remedy: JSON recovery with --force

assumptions.json

• Structure: AssumptionsFile with assumptions (id, phase, category, confidence, validated)
• Valid confidence: "confident", "likely", "unclear"
• Common failures: corrupted JSON, invalid confidence values
• Remedy: JSON recovery with --force

pending-decisions.json

• Structure: FlagsFile with entries (id, type, description, resolved)
• Valid types: "blocker", "issue", "note"
• Common failures: corrupted JSON
• Remedy: JSON recovery with --force

constraints.json

• Ghost file: Go struct is empty {}, content is ignored by all Go code
• Expected state: {} (empty object)
• If content present: warning — content is never read
• Remedy: Reset to {}

Cache Files

• .cache_COLONY_STATE.json — expected, auto-rebuilt by runtime
• .cache_instincts.json — expected, auto-rebuilt by runtime
• Not corruption — these are legitimate cache files

JSONL Files Healthy State

trace.jsonl

• Structure: Each line is a TraceEntry (id, run_id, timestamp, level, topic, payload, source)
• Valid levels: state, phase, pheromone, error, recovery, intervention, token, artifact
• Rotation: 50MB default (pkg/trace/rotate.go)
• Common failures: malformed lines, approaching rotation limit (>45MB)
• Remedy: malformed lines auto-skipped by ReadJSONL; rotation is automatic

event-bus.jsonl

• Structure: Each line is an Event (id, topic, payload, source, timestamp, ttl_days, expires_at)
• TTL: default 30 days, cleanup via bus
• Common failures: malformed lines, expired events
• Remedy: malformed lines auto-skipped; TTL cleanup runs automatically

spawn-tree.txt

• Structure: TSV format with SpawnEntry rows
• Common failures: malformed format
• Remedy: regenerate on next build

Wrapper Parity (Deep Scan)

Expected Counts

Surface	Count	Path
YAML commands	50	.aether/commands/*.yaml
Claude commands	50	.claude/commands/ant/*.md
OpenCode commands	50	.opencode/commands/ant/*.md
Claude agents	25	.claude/agents/ant/*.md
OpenCode agents	25	.opencode/agents/*.md
Codex agents	25	.codex/agents/*.toml
Claude mirror	25	.aether/agents-claude/*.md
Codex mirror	25	.aether/agents-codex/*.toml
Colony skills	11	.aether/skills/colony/*/SKILL.md
Domain skills	18	.aether/skills/domain/*/SKILL.md

Consistency Rules

• Command counts must match across YAML, Claude, and OpenCode
• Agent counts must match across Claude, OpenCode, Codex, and mirrors

Common Failures

• Count mismatch after adding/removing commands
• Missing files after incomplete aether update

Remedies

• Run aether install to regenerate wrappers from YAML sources
• Check .aether/commands/*.yaml as source of truth

Hub Publish Integrity (Deep Scan)

Expected Hub Counts

Surface	Count	Path
Hub Claude commands	50	~/.aether/system/commands/claude/*.md
Hub OpenCode commands	50	~/.aether/system/commands/opencode/*.md
Hub OpenCode agents	25	~/.aether/system/agents/*.md
Hub Codex agents	25	~/.aether/system/codex/*.toml
Hub Codex skills	29	~/.aether/system/skills-codex/*/*/SKILL.md

Failure Signatures

• aether update --force reports Commands (claude) — 0 copied, 0 unchanged
• aether update --force reports Commands (opencode) — 0 copied, 0 unchanged
• aether update --force reports fewer than 25 OpenCode agents

Remedies

• For unreleased local source changes on this machine: run aether publish from the Aether repo (builds binary, syncs hub, verifies version agreement), then aether update --force in target repos. aether install --package-dir "$PWD" also works as backward-compatible fallback
• For isolated source-development on the same machine: run aether publish --channel dev --binary-dest "$HOME/.local/bin" from the Aether repo, then aether-dev update --force in target repos. go run ./cmd/aether install --channel dev --package-dir "$PWD" --binary-dest "$HOME/.local/bin" also works as fallback
• If the change modified aether install itself: bootstrap with go run ./cmd/aether install --package-dir "$PWD" --binary-dest "$HOME/.local/bin"
• For published release runtime updates: run aether update --force --download-binary
• For first-time published installs on a machine with no hub yet: run npx --yes aether-colony@latest

Release Version Integrity

• aether medic --deep includes release integrity scanning via scanIntegrity() which checks binary/hub version agreement and stale publish classification. Issues surface with severity and recovery commands inline.
• aether integrity is the dedicated command for full release pipeline validation. Auto-detects source vs consumer repo context. Source repos get 5 checks (source version, binary version, hub version, companion files, downstream simulation); consumer repos get 4 checks (binary version, hub version, companion files, downstream simulation). Flags: --json (machine-readable output), --channel stable|dev (override channel), --source (force source-repo checks). Cross-reference the operations guide for full workflow documentation.
• .aether/version.json is the source-checkout release version file
• npm/package.json version must equal .aether/version.json
• If these differ, report release version drift before trusting docs or publish instructions
• Release docs are part of the health check: README.md, npm/README.md, AGENTS.md, CLAUDE.md, .codex/CODEX.md, .opencode/OPENCODE.md, RUNTIME UPDATE ARCHITECTURE.md, .aether/docs/publish-update-runbook.md, CHANGELOG.md, and roadmap docs should agree on the install/update story
• For public installs, npx --yes aether-colony@latest should resolve to the same stable version as the current GitHub release
• The npm package page README comes from npm/README.md in the published package, not the root repo README
• Updating the npm website README requires a fresh npm publish; editing npm/README.md in git is not enough
• If install/update/version/binary-download logic changed, treat downstream aether update --force, local aether version, and npm bootstrap verification as part of release integrity
• Stable/public runtime uses aether + ~/.aether/; dev/maintainer runtime uses aether-dev + ~/.aether-dev/
• Dev installs intentionally skip global Claude/OpenCode/Codex home sync by default so source-development does not overwrite the stable command surface on the same machine
• If a release tag exists but gh run list --workflow Release shows no run and gh release view vX.Y.Z shows no release, report that the GitHub release did not materialize and recommend gh workflow run Release -f tag=vX.Y.Z first
• If gh workflow run Release -f tag=vX.Y.Z returns HTTP 422: Actions has been disabled for this user, report that as a GitHub Actions actor/policy failure and recommend another maintainer or the local GoReleaser fallback
• If GitHub workflow dispatch is unavailable or still fails, recommend export GITHUB_TOKEN=\"$(gh auth token)\" && goreleaser release --clean before npm publish
• Treat git push --tags as a release risk. Push a single annotated release tag instead

Version Compatibility

• COLONY_STATE.json version field is "3.0" (string)
• Legacy state names (PAUSED, PLANNED, SEALED, ENTOMBED) are auto-normalized on load
• No structural migration framework exists
• Source-checkout release version detection uses .aether/version.json; installed/runtime detection uses ldflags or the hub version
• Cache files are expected and auto-rebuilt — not data corruption