Aspegio/nelson v1.4.0

v1.4.0 — Hull Integrity & Relief on Station

on GitHub

What's New

Hull Integrity Monitoring

Ships can now monitor their context window consumption — the invisible killer of long-running agent missions. The admiral reads exact token counts directly from Claude Code session JSONL files at each quarterdeck checkpoint and maintains a squadron readiness board tracking every ship's health.

Four-tier threshold system based on remaining context capacity:

No estimation heuristics. No paid APIs. No external dependencies. The token counts come straight from the API usage data that Claude Code already records on every assistant turn.

Relief on Station

When a ship's hull integrity drops to Red, the admiral orchestrates a tactical handover:

1. Damaged ship pauses work and writes a turnover brief to file
2. Admiral spawns a fresh replacement (not necessarily the same ship class)
3. Replacement reads the turnover brief and continues the mission
4. Damaged ship stands down

The turnover brief is comprehensive — mission context, progress log, running plot, files touched, key decisions, hazards, and recommended course of action. Written to file (not a message) to keep the replacement's context clean.

Chained reliefs are supported (A → B → C) with bounded cumulative briefs. Each previous handover gets a single-line summary in the relief chain. Maximum 3 reliefs per task before the admiral should re-scope.

Flagship Self-Monitoring

The admiral monitors its own hull integrity at every checkpoint. At Amber, it begins drafting a flagship turnover brief. At Red, it writes the full brief — including verbatim sailing orders, complete battle plan status, all ship states, and decisions made — and notifies the Admiralty (human) that a new session must take over.

Session Hygiene

New sessions start clean. The admiral clears stale damage reports and turnover briefs from .claude/nelson/ before forming the squadron. Previous session data can optionally be archived. Resumed sessions skip cleanup and read existing reports to recover state.

Token Counter Script

scripts/count-tokens.py — a zero-dependency Python script with three modes:

# Flagship checks itself
python scripts/count-tokens.py --session session.jsonl --ship "HMS Victory"

# Full squadron readiness board
python scripts/count-tokens.py --squadron /path/to/{session-id}/

# Plain text fallback (heuristic)
python scripts/count-tokens.py --file document.txt --ship "HMS Argyll"

The --squadron mode scans the flagship JSONL and all subagent files in {session-id}/subagents/ in one pass. Ships can't easily self-monitor (they don't know their own agent ID), but that's the correct pattern — the flagship monitors everyone.

Other Improvements

• Ambiguity check on briefs — The admiral now reviews the user's brief for ambiguity and asks for clarification before drafting sailing orders
• Documentation file trees synced with current branch state
• Skill alignment with Anthropic's skills guide conventions

New Files

skills/nelson/references/
  admiralty-templates/
    damage-report.md        — JSON template for hull integrity reports
    turnover-brief.md       — Standard and flagship handover briefs
  damage-control/
    hull-integrity.md       — Threshold definitions & squadron readiness board
    relief-on-station.md    — Planned ship replacement procedure
    session-hygiene.md      — Clean start procedure for new sessions
scripts/
  count-tokens.py           — Token counter for hull integrity monitoring

Live Data

Squadron readiness board captured during the session that built this release:

The flagship was at Red hull integrity by the end of the mission — proving exactly why this feature is needed.