journal

Journal

Project audit trail. Every substantive task = one entry. Append at END. Last entry = newest.

Pre-flight install (MANDATORY - run every session, no asking)

Always run this single line BEFORE invoking any journal-tools subcommand. 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:

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.

Ships journal-tools CLI (check, sort, archive, standardize). Verify: journal-tools --help. Never skip this step. Never ask the user whether to install - just run the line.

Commands

Command	Use
/journal:create	INIT empty journal. Backfill from conversation context. Refuses if file exists.
/journal:update	DEFAULT. Append new entry. Extend last entry only if same task, pre-release.
/journal:archive	Move old entries to JOURNAL_ARCHIVE.md. Triggered >40 entries.
/journal:standardize	REPAIR. For each entry the validator warned on (over Standard target, over Extended max, or false-advertising marker), a focused claude -p subprocess decides Extended vs Condense vs Drop-marker; the CLI applies it. Use after journal-tools check reports word-count warnings - never inline-edit oversized entries by hand.
/journal:article	EXTRACT. For entries over the Extended max (>400 words), pull the depth into a standalone article under docs/ and condense the entry to a Standard-tier summary linking to the article. Asks the user for title / location / scope / summary length via AskUserQuestion.