@kulapard/pi-caveman 0.4.3 → 0.6.0

package/AGENTS.md

@@ -4,22 +4,27 @@ Project memory. Non-obvious only.
 
 ## Architecture (do not rebuild)
 
-- `extensions/caveman.ts` = Pi extension. `extensions/caveman-core.ts` = pure SDK-free logic (`normalizeMode`, `modeInstructions`, `VALID_MODES`, regexes). Unit-testable without fake SDK.
-- Mode state **session-scoped**: `pi.appendEntry("caveman-mode", …)`, restored from `ctx.sessionManager.getBranch()` on `session_start`. New session always `off`. No cross-session config/env.
-- Activation = `before_agent_start` appends `modeInstructions(mode)`. Statusline = `ctx.ui.setStatus("caveman", …)` guarded by `hasUI`.
-- Extension `modeInstructions` = **canonical** activator. `skills/caveman/SKILL.md` = fallback for hosts loading skills but not extension. If both active, model sees both rule sets — intentional redundancy, no de-dupe.
+- `extensions/caveman.ts` = Pi extension. `extensions/caveman-core.ts` holds SDK-free logic (`normalizeMode`, `modeInstructions`, `VALID_MODES`, regexes). Testable without fake SDK.
+- Mode state **session + project-scoped**: `pi.appendEntry("caveman-mode", …)` restores from `ctx.sessionManager.getBranch()` on `session_start`; since v0.4.3 `extensions/caveman-state.ts` reads/writes `.pi/caveman-mode.json`. Session entry overrides project default; missing state file → `off`. No global/env default.
+- `before_agent_start` appends `modeInstructions(mode)`. Statusline = `ctx.ui.setStatus("caveman", …)` guarded by `hasUI`.
+- Extension `modeInstructions` = **canonical** activator. `skills/caveman/SKILL.md` = fallback when extension not loaded. Both active → model sees both rule sets; intentional redundancy, no de-dupe.
 - Pi 0.80.2 has **no `agents/` subagent mechanism**. `agents/cavecrew-*.md` = reference personas only; cavecrew optional/out-of-scope.
 
 ## Invariants
 
-- **SDK import `import type` only** in `extensions/*.ts`. JS tests run via `--experimental-strip-types`, erases type-only imports. Value import from `@earendil-works/pi-coding-agent` breaks tests — `tests/extension.test.mjs` asserts this.
-- **Verbatim preservation**: caveman-compress never changes code blocks, inline code, URLs, paths, commands, exact error strings. Skill instructs self-validate against original. Mismatch unfixable → restore from `.original` backup created in same invocation (stale backups rejected before compression).
-- `caveman-compress` is **prompt-only**: Pi agent compresses with own model + file tools, driven by `SKILL.md`. No Python, no external model CLI. Coverage = `tests/compress-docs.test.mjs`.
+- **SDK import `import type` only** in `extensions/*.ts`. JS tests use `--experimental-strip-types`, erases type-only imports. Value import from `@earendil-works/pi-coding-agent` breaks tests — `tests/extension.test.mjs` asserts this.
+- **Verbatim preservation**: caveman-compress never changes code blocks, inline code, URLs, paths, commands, exact error strings. Self-validate against original. Mismatch unfixable → restore from `.original` backup created in same invocation; stale backups rejected before compression.
+- `caveman-compress` **prompt-only**: Pi agent compresses with own model + file tools, driven by `SKILL.md`. No Python, no external model CLI. Coverage = `tests/compress-docs.test.mjs`.
+- `/caveman-compress` supports `--force`: overwrites existing `.original.<ext>` backup instead of aborting.
+
+## Releases
+
+Tag push triggers npm publish via `.github/workflows/publish.yml`. On release, create GitHub Release with same tag; paste matching `CHANGELOG.md` section into notes.
 
 ## Changelog
 
-Every notable change must update `CHANGELOG.md` under `[Unreleased]`. Before finishing task, run `npm run changelog:check` to confirm changelog updated for files changed. CI runs same check on every PR.
+Every notable change → `CHANGELOG.md` `[Unreleased]`. Before finish, run `npm run changelog:check`. CI runs same check per PR.
 
-- `npm test` runs `pretest` (`npm run typecheck` → `tsc --noEmit`), then `node --test tests/**/*.test.mjs`. Typecheck failures fail test run.
+- `npm test` = `pretest` (`npm run typecheck` → `tsc --noEmit`), then `node --test tests/**/*.test.mjs`. Typecheck failures fail test run.
 - Node `--test` glob expanded by runner, not shell. Directory-recursion `--test tests/` does **not** work on current Node — keep glob.
 - Tests are **phantom-reference guards** (`tests/stats-docs.test.mjs`, `tests/cavecrew-docs.test.mjs`, `tests/compress-docs.test.mjs`): docs must not mention Claude-Code hooks layer, plugin install path, `⛏` badge, Claude-only subagent presets, broken asset paths. Do not reintroduce.

package/CHANGELOG.md

@@ -7,13 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-06-29
+
+### Added
+
+- Release notes reminder: when tagging a release, also create a GitHub Release with the same tag and paste the relevant `CHANGELOG.md` section into the release notes.
+
+### Changed
+
+- Statusline no longer appends `ctx:XX%`; shows only `caveman:<mode>`.
+- Re-compressed `AGENTS.md` with `/caveman-compress --force` to reduce session token load.
+
+### Repository
+
+- `.gitignore` now excludes `.pi/caveman-mode.json` (project-scoped mode state).
+
+## [0.5.0] - 2026-06-29
+
+### Added
+
+- `/caveman-compress` now accepts an optional `--force` flag. With `--force`, an existing `.original.<ext>` backup is overwritten instead of aborting.
+
 ### Changed
 
-- Caveman mode is now project-scoped: `.pi/caveman-mode.json` in the working
-  directory persists the mode across new sessions, while session entries still
-  override it for the current session. Falls back to `off` when no state exists.
-- Status bar now appends live context usage (`ctx:XX%`) when a caveman mode is
-  active and Pi exposes usage data. Updates on mode changes and at each turn end.
+- Updated README, AGENTS.md, caveman-help, and caveman-compress docs to reflect the project-scoped persistence added in v0.4.3 and the new `--force` flag.
 
 ## [0.4.2] - 2026-06-29
 
@@ -120,7 +137,9 @@ port of [caveman](https://github.com/JuliusBrussee/caveman).
   token, automatic provenance, a tag-equals-version guard, and a concurrency
   group).
 
-[Unreleased]: https://github.com/kulapard/pi-caveman/compare/v0.4.2...HEAD
+[Unreleased]: https://github.com/kulapard/pi-caveman/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/kulapard/pi-caveman/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/kulapard/pi-caveman/compare/v0.4.2...v0.5.0
 [0.4.2]: https://github.com/kulapard/pi-caveman/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/kulapard/pi-caveman/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/kulapard/pi-caveman/compare/v0.3.0...v0.4.0

package/README.md

@@ -92,7 +92,7 @@ session ends.
 | `/caveman-help` | Show the quick-reference card. |
 | `/caveman-commit [notes]` | Generate a terse Conventional Commit message. Does **not** commit. |
 | `/caveman-review [scope]` | One-line-per-finding code review comments. |
-| `/caveman-compress <file>` | Compress a prose file via the caveman-compress skill. |
+| `/caveman-compress <file> [--force]` | Compress a prose file via the caveman-compress skill. `--force` overwrites an existing `.original` backup. |
 | `/caveman-stats` | Load the stats skill (an on-demand, model-driven estimate). |
 
 ## Natural-language activation
@@ -105,18 +105,18 @@ switches mode on phrases like:
 - **Deactivate:** "stop caveman", "normal mode", "disable caveman" → turns it
   off.
 
-## Session-scoped behavior
+## Session and project-scoped behavior
 
-Mode state is **session-scoped**. It is stored as a session entry and restored
-across a `/reload` within the same session, but a **new session always starts
-with caveman off** — by design. There is no cross-session config file or global
-default that auto-enables it.
+Mode state is stored as a session entry, so it survives a `/reload` within the
+same session. Since v0.4.3 it is also persisted per project in
+`.pi/caveman-mode.json`, so a **new session in the same project directory**
+restores the last used mode. A session entry always overrides the project
+default, and a project without a state file falls back to `off`.
 
 ## Statusline indicator
 
 When a UI is attached, the statusline shows the active mode as
-`caveman:<mode>` (for example `caveman:ultra`). When caveman is off the indicator
-is cleared.
+`caveman:<mode>` (for example `caveman:ultra`). When caveman is off the indicator is cleared.
 
 ## Compression vs. upstream MCP shrink
 

package/extensions/caveman.ts

@@ -20,7 +20,7 @@ Commands:
 - /caveman-help — show this card.
 - /caveman-commit [notes] — generate Conventional Commit message. Does not commit.
 - /caveman-review [scope] — terse review comments.
-- /caveman-compress <file> — compress prose file via caveman-compress skill.
+- /caveman-compress <file> [--force] — compress prose file via caveman-compress skill. --force overwrites an existing .original backup.
 - /caveman-stats — load stats skill/help.
 
 Mode persists across sessions in the same project via \`.pi/caveman-mode.json\`, and
@@ -32,13 +32,7 @@ export default function cavemanExtension(pi: ExtensionAPI) {
 
 	function setStatus(ctx?: ExtensionContext) {
 		if (!ctx?.hasUI) return;
-		const usage = ctx.getContextUsage?.();
-		const suffix =
-			usage?.percent != null ? ` ctx:${Math.round(usage.percent)}%` : "";
-		ctx.ui.setStatus(
-			"caveman",
-			mode === "off" ? undefined : `caveman:${mode}${suffix}`,
-		);
+		ctx.ui.setStatus("caveman", mode === "off" ? undefined : `caveman:${mode}`);
 	}
 
 	function persistMode(nextMode: StoredMode, ctx?: ExtensionContext) {
@@ -121,14 +115,20 @@ export default function cavemanExtension(pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("caveman-compress", {
-		description: "Compress prose/memory file into caveman style",
+		description:
+			"Compress prose/memory file into caveman style (optional --force)",
 		handler: async (args, ctx) => {
-			const target = args?.trim();
+			const raw = args?.trim() ?? "";
+			const tokens = raw.split(/\s+/).filter(Boolean);
+			const force = tokens.includes("--force");
+			const target = tokens.filter((t) => t !== "--force").join(" ");
 			if (!target) {
-				ctx.ui.notify("Usage: /caveman-compress <file>", "error");
+				ctx.ui.notify("Usage: /caveman-compress <file> [--force]", "error");
 				return;
 			}
-			pi.sendUserMessage(`/skill:caveman-compress ${target}`);
+			pi.sendUserMessage(
+				`/skill:caveman-compress ${target}${force ? " --force" : ""}`,
+			);
 		},
 	});
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kulapard/pi-caveman",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "description": "Caveman for Pi: ultra-compressed agent output that preserves technical substance. Six intensity modes, slash commands, natural-language activation, and a session statusline.",
   "type": "module",
   "license": "MIT",

package/skills/caveman-compress/README.md

@@ -25,7 +25,7 @@ AGENTS.md          ← compressed (the agent reads this — fewer tokens every s
 AGENTS.original.md ← human-readable backup (snapshot taken at first compression)
 ```
 
-Original never lost — first compression writes a verbatim backup. To edit and re-compress, **edit `AGENTS.md` itself**, then delete or rename the existing `AGENTS.original.md` so the next `/caveman-compress` can create a fresh backup.
+Original never lost — first compression writes a verbatim backup. To edit and re-compress, **edit `AGENTS.md` itself**, then delete or rename the existing `AGENTS.original.md` so the next `/caveman-compress` can create a fresh backup. Or use `/caveman-compress AGENTS.md --force` to overwrite the existing backup in one step.
 
 ## Benchmarks
 
@@ -77,7 +77,7 @@ its own model and file tools — there is no separate tool or language to instal
 ## Usage
 
 ```
-/caveman-compress <filepath>
+/caveman-compress <filepath> [--force]
 ```
 
 Examples:
@@ -87,6 +87,7 @@ Examples:
 /caveman-compress CLAUDE.md
 /caveman-compress docs/preferences.md
 /caveman-compress todos.md
+/caveman-compress AGENTS.md --force
 ```
 
 ### What files work

package/skills/caveman-compress/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Compress natural language memory files (AGENTS.md, CLAUDE.md, todos, preferences) into caveman
   format to save input tokens. Preserves all technical substance, code, URLs, and structure.
   Compressed version overwrites the original file. Human-readable backup saved as FILE.original.<ext> (same extension as the source).
-  Trigger: /caveman-compress FILEPATH or "compress memory file"
+  Trigger: /caveman-compress FILEPATH [--force]
 ---
 
 # Caveman Compress
@@ -15,16 +15,19 @@ Compress natural language files (`AGENTS.md`, `CLAUDE.md`, todos, preferences) i
 
 ## Trigger
 
-`/caveman-compress <filepath>` or when user asks to compress a memory file.
+`/caveman-compress <filepath>` or when user asks to compress a memory file. Append `--force` to overwrite an existing `.original.<ext>` backup instead of aborting.
 
 ## Process
 
-You (the Pi agent) perform the compression directly — there is no separate tool to run. Given `/caveman-compress <filepath>`:
+You (the Pi agent) perform the compression directly — there is no separate tool to run. Given `/caveman-compress <filepath>` (optionally with `--force`):
 
 1. **Skip backups.** If the path ends in `.original.<ext>` or, for extensionless files, in `.original` (e.g. `AGENTS.original.md`, `NOTES.original`), stop — never compress a backup file.
 2. **Check it is compressible** per **Boundaries** below: prose files (`.md`, `.txt`, `.rst`, `.typ`, `.typst`, `.tex`, or extensionless natural language). If it is code/config (`.py`, `.js`, `.ts`, `.json`, `.yaml`, …) or larger than ~500 KB, report it is out of scope and stop.
 3. **Read** the file's full contents.
-4. **Back up the original.** If a `.original`/`.original.<ext>` backup already exists, **abort** and tell the user to remove or rename the stale backup before re-compressing. Otherwise write a verbatim copy to `<filename>.original.<ext>` (or `<filename>.original` for extensionless files) before any rewrite.
+4. **Back up the original.** If a `.original`/`.original.<ext>` backup already exists:
+   - Without `--force`, **abort** and tell the user to remove or rename the stale backup before re-compressing.
+   - With `--force`, overwrite the existing backup with a verbatim copy of the current source before any rewrite.
+   If no backup exists, write a verbatim copy to `<filename>.original.<ext>` (or `<filename>.original` for extensionless files) before any rewrite.
 5. **Rewrite** the file in place, applying the **Compression Rules** below. Treat code blocks, inline code, URLs, paths, commands, headings, and table structure as read-only regions.
 6. **Self-validate** against the contents you read in step 3: every protected token — fenced and inline code, URLs, file paths, heading text, table structure, dates/version numbers — must be byte-for-byte identical. If any changed, fix just that region; if you cannot make it identical, restore the file from the backup you wrote in step 4 and report the failure rather than leave a corrupted file.
 7. **Report** the result: bytes before/after and the approximate reduction.

package/skills/caveman-help/README.md

@@ -4,7 +4,13 @@ Quick-reference card. One shot, no mode change.
 
 ## What it does
 
-Prints a cheat sheet of all caveman modes, sibling skills, deactivation triggers, and how mode lasts for the session (set with `/caveman`, resets to `off` on a new session — no config file or env var). One-shot display — does not flip the active mode, write flag files, or persist anything. Use when you forget the slash commands.
+Prints a cheat sheet of all caveman modes, sibling skills, deactivation
+triggers, and how mode persists: it is stored as a session entry (survives
+`/reload`), and since v0.4.3 it is also saved per project in
+`.pi/caveman-mode.json` (a new session in the same project directory restores
+the last mode). No config file? Falls back to `off`. One-shot display — does not
+flip the active mode, write flag files, or persist anything. Use when you forget
+the slash commands.
 
 ## How to invoke
 

package/skills/caveman-help/SKILL.md

@@ -29,7 +29,7 @@ Mode stick until changed or session end.
 |-------|---------|-----------|
 | **caveman-commit** | `/caveman-commit` | Terse commit messages. Conventional Commits. ≤50 char subject. |
 | **caveman-review** | `/caveman-review` | One-line PR comments: `L42: bug: user null. Add guard.` |
-| **caveman-compress** | `/caveman-compress <file>` | Compress .md files to caveman prose. Saves ~46% input tokens. |
+| **caveman-compress** | `/caveman-compress <file> [--force]` | Compress .md files to caveman prose. Saves ~46% input tokens. `--force` overwrites stale backup. |
 | **caveman-stats** | `/caveman-stats` | On-demand, model-driven estimate of tokens saved this session. |
 | **caveman-help** | `/caveman-help` | This card. |
 
@@ -41,12 +41,16 @@ Say "stop caveman" or "normal mode". Resume anytime with `/caveman`.
 
 Keep user's language by default. User write Portuguese → reply Portuguese caveman. Compress the style, not the language. Technical terms, code, commands, commit types, and exact error strings stay verbatim unless user ask for translation.
 
-## Mode lasts the session
+## Mode persistence
 
-`/caveman` (no argument) = `full`. Pick another with `/caveman ultra`, `/caveman lite`, etc.
+Mode set per session entry, so it survives `/reload`. Since v0.4.3 it is also
+saved per project in `.pi/caveman-mode.json`; a new session in the same project
+directory restores the last mode. Session entry overrides project default. No
+config file? Falls back to `off`.
 
-Mode set per session. New session start → mode `off`; activate again with `/caveman`. No config file, no env var — the `/caveman` command is the only switch.
+`/caveman` (no argument) = `full`. Pick another with `/caveman ultra`,
+`/caveman lite`, etc. Say "stop caveman" or "normal mode" to turn off.
 
 ## More
 
-Full docs: https://github.com/kulapard/pi-caveman
+Full docs: <https://github.com/kulapard/pi-caveman>