archive

Archive Journal

Prefer the programmatic tool. It preserves numbering and appends idempotently.

Pre-flight install (MANDATORY, no asking)

Before invoking journal-tools archive, always run:

python3 -m pip install --user --upgrade stellars-claude-code-plugins 2>&1 | tail -1
LIB=$(python3 -c "import importlib.metadata as m;print(m.version('stellars-claude-code-plugins'))" 2>/dev/null) || { echo "FATAL: toolkit unavailable"; exit 1; }
PLUG=$(grep -m1 '"version"' "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" 2>/dev/null | cut -d'"' -f4)
OLDER=$(printf '%s\n%s\n' "$LIB" "$PLUG" | sort -V | head -1)
[ -n "$PLUG" ] && [ "$LIB" != "$PLUG" ] && [ "$OLDER" = "$LIB" ] && { echo "STALE: library $LIB older than plugin $PLUG - refusing to run on an outdated CLI; re-run the upgrade"; exit 1; }
echo "toolkit $LIB"

Run the CLI without touching the caller's project. The gate above puts it on PATH, so the bare command name is the whole invocation. uv run instead resolves whatever project the working directory sits in and writes uv.lock and .venv into it, so if you reach for uv pass --no-project (uv run --no-project <cli> ...) - it skips project discovery, leaves the tree untouched and still finds the same PATH binary. --no-sync and --frozen are not substitutes; both still create .venv.

The upgrade always runs - a stale-but-importable install is exactly the failure this gate prevents, and the reinstall also repairs a stale shim on PATH whose package is uninstalled in the active Python. Never skip. Never ask.

Primary path (programmatic)

journal-tools archive .claude/JOURNAL.md

Default: threshold 40, keep last 20. Flags: --keep-last N, --threshold N, --archive-path PATH. If uv not available, try plain journal-tools archive ... or python -m stellars_claude_code_plugins.journal.journal_tools archive ....

After run:

1. Read .claude/JOURNAL.md last 5 lines — confirm last 20 entries remain, note at top links to archive
2. Read JOURNAL_ARCHIVE.md beside the real journal file (.agents/JOURNAL_ARCHIVE.md, Layout in skills/journal/SKILL.md) last 5 lines — confirm entries appended, numbering continuous
3. Run journal-tools check .claude/JOURNAL.md — exit 0 = clean