Bumblebiber/o9k-release

/o9k-release — Release Checklist

Run this checklist before every npm publish of its-over-9k. Every release touches code, skills, config, and documentation — this skill ensures nothing falls through the cracks.

---

Step 0: Get Explicit Permission (R0027)

Always pause before proceeding. Even when the user invoked this skill, get explicit go-ahead for this specific release. Don't infer approval from prior context — "apply the changes" is not "publish".

Show the user:

• Current version → target version
• Bump type (patch / minor / major) and the reason
• Short summary of what's changing (1-3 bullets)

Then ask: "Soll ich publishen?" / "OK to release?" — wait for an explicit yes. If the user pauses, defers, or says "noch nicht", stop and do not run any further steps. The fact that the user asked you to prepare a release is not permission to ship it.

---

Step 1: Version Bump

npm version patch --no-git-tag-version  # or minor/major as appropriate

Decide the version type based on what changed:

• patch: bugfixes, skill text updates, small improvements
• minor: new features (new tools, new prefix, new config options, new skills)
• major: breaking changes (schema changes, removed tools, API changes)

---

Step 2: Build & Type Check

npx tsc --noEmit   # type check first (fast)
npx tsc             # full build

Fix any errors before proceeding.

---

Step 3: Skill Audit

Every code change can affect skill documentation. Check each skill against the current code:

| Skill | Check for | Common triggers | |-------|-----------|-----------------| | o9k-write | write_memory format, body syntax (>), char limits, tag rules | Changes to parseTree, write(), validation logic | | o9k-read | read_memory output format, load_project display, O-entry format | Changes to formatBulkRead, formatRecentOEntries, load_project rendering | | o9k-config | New config parameters, changed defaults, removed options | Changes to HmemConfig interface, DEFAULT_CONFIG, loadHmemConfig | | o9k-update | All user-facing changes: new MCP tools, removed tools, new CLI commands, statusline changes, new config options, behavior changes, setup steps. This is the changelog users read when upgrading. | Every release — if a user upgrading needs to know about it, it goes here. | | o9k-curate | Curation rules (self + foreign-file), hmem_path param, new node types, new tags | New tagged node types (#checkpoint-summary, #skill-dialog), schema changes, hmem_path-capable tool changes | | o9k-new-project | P-entry schema (R0009), write_memory format | Changes to P-entry structure or write format | | o9k-setup | Hook scripts, init flow, MCP config format | Changes to hooks, CLI commands, environment variables | | o9k-wipe | Checkpoint references, context threshold | Changes to checkpointMode, contextTokenThreshold | | o9k-sync-setup | Sync config format, sync commands | Changes to sync parsing, o9k-sync integration |

How to check: For each skill, grep for key terms from the code change:

grep -l "relevant_term" skills/*/SKILL.md

If a skill references something you changed, read and update it.

---

Step 4: Config Schema Check

If you added new config parameters:

1. Added to HmemConfig interface? (o9k-config.ts)
2. Added to DEFAULT_CONFIG? (o9k-config.ts)
3. Parsing logic in loadHmemConfig? (o9k-config.ts)
4. Added to MEMORY_KEYS set? (o9k-config.ts)
5. Included in saveHmemConfig output? (o9k-config.ts)
6. Documented in o9k-config skill?

---

Step 5: Prefix Check

If you added or changed prefixes:

1. Added to DEFAULT_PREFIXES? (o9k-config.ts)
2. Added to DEFAULT_PREFIX_DESCRIPTIONS? (o9k-config.ts)
3. Documented in o9k-write skill (prefix list)?
4. Documented in o9k-read skill?

---

Step 6: Tool Parameter Check

If you changed MCP tool parameters (added, removed, changed types):

1. Zod schema updated in mcp-server.ts?
2. Using z.coerce.boolean() for booleans (not z.boolean())?
3. Tool description updated?
4. Affected skills updated?

---

Step 7: Migration Check

If the release introduces schema changes:

1. MIGRATIONS array updated in o9k-store.ts? (ALTER TABLE for new columns)
2. o9k-update skill documents the migration step?
3. Auto-migration tested with an old DB?

---

Step 7b: Hook Artifact Audit

The npm package ships hook scripts that end users must redeploy after every update — and on this dev device (Strato), Hermes itself runs against the same hooks. If any of these files moved, changed args, or got new dependencies, the release skill is the last line of defence before users hit broken hooks.

Files to audit on every release:

| Path | Used by | Deployed via | |------|---------|--------------| | hermes-hooks/o9k-startup.sh | Hermes Agent (pre_llm_call) | manual cp to ~/.hermes/agent-hooks/ | | hermes-hooks/o9k-log-exchange.sh | Hermes Agent (post_llm_call) | manual cp to ~/.hermes/agent-hooks/ | | hermes-hooks/hmem-statusline.sh | Hermes Agent statusline | manual cp to ~/.hermes/agent-hooks/ | | hermes-hooks/hermes-cli-hmem-statusline.patch | Hermes CLI statusbar injection | git apply in ~/.hermes/hermes-agent | | plugins/hermes-hmem/ | Hermes hmem plugin (Python) | manual symlink + enable | | scripts/hmem-session-inject.sh | Claude Code SessionStart | hmem init / hmem setup-hook | | scripts/hmem-statusline.sh | Claude Code statusline | hmem init |

For each file changed in this release:

1. Run it locally if it's a shell script — syntax errors only surface at runtime
2. Confirm the deployment instruction in o9k-update is still accurate — if a path moved or a flag changed, o9k-update is the user's only signal
3. Apply the patch dry-run if hermes-cli-hmem-statusline.patch changed: cd ~/.hermes/hermes-agent && git apply --check ~/projects/hmem/hermes-hooks/hermes-cli-hmem-statusline.patch
4. Mention hook changes in release notes — users won't re-run the deployment steps unless prompted

Important: hook BEHAVIOR can change even if the .sh files don't, because the scripts call hmem hook-startup / hmem log-exchange / hmem statusline — and any change to cli-hook-startup.ts, cli-context-inject.ts, or cli-log-exchange.ts shifts what those scripts produce. Audit by behavior, not just file mtime: if you touched any cli-*hook* / cli-context-inject / cli-log-exchange / cli-statusline source file, the Hermes hooks effectively changed.

Before publish — divergence check: Compare deployed vs repo to catch local edits that never made it back:

for f in o9k-startup.sh o9k-log-exchange.sh hmem-statusline.sh; do
  diff -q ~/projects/hmem/hermes-hooks/$f ~/.hermes/agent-hooks/$f
done

If anything differs, decide: improvement (copy to repo before release) or accidental edit (restore from repo). Never publish with a known divergence — the npm version will overwrite Hermes-side improvements on other devices.

Deployment options on this dev device (Hermes host):

Option A — Symlink (recommended for dev devices): ~/.hermes/agent-hooks/*.sh symlinked to ~/projects/hmem/hermes-hooks/*.sh. Any repo change is instantly live; no redeploy step needed.

for f in o9k-startup.sh o9k-log-exchange.sh hmem-statusline.sh; do
  ln -sf ~/projects/hmem/hermes-hooks/$f ~/.hermes/agent-hooks/$f
done

Option B — Copy (default for end users, isolates deployment): explicit cp and chmod each time.

cp ~/projects/hmem/hermes-hooks/*.sh ~/.hermes/agent-hooks/ && chmod +x ~/.hermes/agent-hooks/*.sh

If the CLI patch changed: cd ~/.hermes/hermes-agent && git apply ~/projects/hmem/hermes-hooks/hermes-cli-hmem-statusline.patch

There is no hmem deploy-hermes-hooks command yet — if you find yourself doing this manually for the Nth time, consider adding one with a --symlink flag (would also satisfy P0048.16.1 — no manual steps for end users).

---

Step 8: Commit & Publish

git add src/ skills/ package.json package-lock.json
git commit -m "feat/fix: description

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>"
npm publish
git push

---

Step 8b: Release Notes (always — including patches)

Every release gets release notes — no exceptions for "trivial" patches. The GitHub release page is the canonical "what changed in vX.Y.Z" that users check when something behaves differently after an update.

cd ~/projects/hmem
VERSION=$(node -p "require('./package.json').version")
gh release create "v$VERSION" \
  --title "v$VERSION — <short summary>" \
  --notes "$(cat <<'EOF'
## Changes
- <bullet 1>
- <bullet 2>

## Impact / Migration
<paragraph — or omit if obvious>
EOF
)"

Sizing:

• Patch: 1–3 bullets, no migration section needed if behavior is purely additive
• Minor: bullets per feature, brief migration paragraph if any config touched
• Major: full breaking-changes list, before/after examples, migration steps

Never skip with "it's just a tiny patch" — undocumented patches are exactly the ones that surprise users later.

---

Step 9: Post-Publish

1. Verify on npm: npm view its-over-9k version
2. Update Overview version node: update_memory(id="P0048.1.1", content="vX.Y.Z released (YYYY-MM-DD)"). If no version node exists yet, create one: append_memory(id="P0048.1", title="vX.Y.Z released (YYYY-MM-DD)")
3. Sync to devices: o9k-sync push (if applicable)
4. Redeploy hooks on this Hermes host (if hook files changed in this release):

   cp ~/projects/hmem/hermes-hooks/*.sh ~/.hermes/agent-hooks/ && chmod +x ~/.hermes/agent-hooks/*.sh
   # If hermes-cli patch changed: cd ~/.hermes/hermes-agent && git apply ~/projects/hmem/hermes-hooks/hermes-cli-hmem-statusline.patch
   # If Claude Code hooks changed: hmem setup-hook  (re-installs ~/.claude/hooks/hmem-session-inject.sh)
   

5. Update hmem P-entry protocol: append_memory(id="P0048.7", content="\tHandoff: vX.Y.Z released...")
6. Notify user via Telegram if relevant

---

Quick Reference: What changed → What to check

| Code area | Skills to check | |-----------|----------------| | o9k-store.ts (write/read) | o9k-write, o9k-read, o9k-curate | | o9k-store.ts (O-entries) | o9k-read, o9k-curate | | o9k-config.ts | o9k-config, o9k-update, o9k-setup | | mcp-server.ts (new/removed tools) | o9k-write, o9k-read (tool params), o9k-update | | mcp-server.ts (load_project) | o9k-read, o9k-new-project | | cli-statusline.ts | o9k-update (statusline changes users see) | | cli.ts (new commands) | o9k-update (new CLI commands for users), o9k-setup | | cli-checkpoint.ts | o9k-config (checkpoint docs), o9k-read (summary docs) | | cli-log-exchange.ts | o9k-setup (hook docs) | | hermes-hooks/* | Step 7b + o9k-update (deployment instructions) | | plugins/hermes-hmem/* | Step 7b + o9k-update | | scripts/hmem-session-inject.sh, scripts/hmem-statusline.sh | Step 7b + o9k-setup | | cli-context-inject.ts | o9k-wipe, o9k-setup, o9k-update | | cli-hook-startup.ts | o9k-setup (first-message context docs), o9k-update (user-visible behavior) | | Any new skill added | o9k-update (list of skills to sync) | | Any new user-visible behavior | o9k-update — always |