@kulapard/pi-caveman 0.4.2 → 0.5.0

package/AGENTS.md

@@ -5,20 +5,25 @@ 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.
+- 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` also reads/writes `.pi/caveman-mode.json`
+  in the project directory. A session entry overrides the project default; a
+  project without a state file falls back to `off`. No global/env default.
 - 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.
+- Extension `modeInstructions` = **canonical** activator. `skills/caveman/SKILL.md` = fallback for hosts loading skills but not extension. 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).
+- **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` 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`.
+- `/caveman-compress` supports `--force`: overwrites existing `.original.<ext>` backup instead of aborting.
 
 ## 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 update `CHANGELOG.md` under `[Unreleased]`. Before finishing, run `npm run changelog:check`. CI runs same check on every PR.
 
 - `npm test` runs `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.

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- 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
 
 ### Changed
@@ -112,7 +122,8 @@ 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.5.0...HEAD
+[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,19 @@ 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`), and appends live context usage
+as `ctx:XX%` when Pi provides it. When caveman is off the indicator is cleared.
 
 ## Compression vs. upstream MCP shrink
 

package/extensions/caveman-state.ts

@@ -0,0 +1,49 @@
+// Project-scoped persistence for caveman mode.
+// This is a workaround until Pi exposes SettingsManager to extensions
+// (tracked upstream as pi-coding-agent issue #4981).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { normalizeMode, type StoredMode } from "./caveman-core.ts";
+
+const STATE_DIR = ".pi";
+const STATE_FILE = "caveman-mode.json";
+
+function statePath(cwd: string): string {
+	return join(cwd, STATE_DIR, STATE_FILE);
+}
+
+/**
+ * Load the project-scoped caveman mode default. Returns `undefined` when no
+ * state file exists or it cannot be read, so the caller can fall back to the
+ * session-scoped default (`off`).
+ */
+export function loadProjectMode(cwd: string): StoredMode | undefined {
+	const path = statePath(cwd);
+	if (!existsSync(path)) return undefined;
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf8"));
+		return normalizeMode(raw.mode);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Persist the caveman mode for this project directory. Returns `true` on
+ * success; failures are silent so that session operation is never blocked by
+ * disk issues.
+ */
+export function saveProjectMode(cwd: string, mode: StoredMode): boolean {
+	try {
+		const dir = join(cwd, STATE_DIR);
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+		writeFileSync(
+			statePath(cwd),
+			JSON.stringify({ mode, updatedAt: Date.now() }, null, 2),
+		);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/extensions/caveman.ts

@@ -10,6 +10,7 @@ import {
 	normalizeMode,
 	type StoredMode,
 } from "./caveman-core.ts";
+import { loadProjectMode, saveProjectMode } from "./caveman-state.ts";
 
 const HELP_TEXT = `# Caveman for Pi
 
@@ -19,18 +20,25 @@ 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 in current Pi session and survives /reload via session state.
-Code, commands, API names, file paths, and exact errors stay verbatim.`;
+Mode persists across sessions in the same project via \`.pi/caveman-mode.json\`, and
+survives /reload via session state. Code, commands, API names, file paths, and
+exact errors stay verbatim.`;
 
 export default function cavemanExtension(pi: ExtensionAPI) {
 	let mode: StoredMode = "off";
 
 	function setStatus(ctx?: ExtensionContext) {
 		if (!ctx?.hasUI) return;
-		ctx.ui.setStatus("caveman", mode === "off" ? undefined : `caveman:${mode}`);
+		const usage = ctx.getContextUsage?.();
+		const suffix =
+			usage?.percent != null ? ` ctx:${Math.round(usage.percent)}%` : "";
+		ctx.ui.setStatus(
+			"caveman",
+			mode === "off" ? undefined : `caveman:${mode}${suffix}`,
+		);
 	}
 
 	function persistMode(nextMode: StoredMode, ctx?: ExtensionContext) {
@@ -40,7 +48,7 @@ export default function cavemanExtension(pi: ExtensionAPI) {
 	}
 
 	pi.on("session_start", (_event, ctx) => {
-		mode = "off";
+		mode = loadProjectMode(ctx.cwd) ?? "off";
 		for (const entry of ctx.sessionManager.getBranch() as Array<{
 			type?: string;
 			customType?: string;
@@ -73,6 +81,7 @@ export default function cavemanExtension(pi: ExtensionAPI) {
 				return;
 			}
 			persistMode(nextMode, ctx);
+			saveProjectMode(ctx.cwd, nextMode);
 			ctx.ui.notify(
 				nextMode === "off" ? "Caveman disabled" : `Caveman ${nextMode} enabled`,
 				"info",
@@ -112,14 +121,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" : ""}`,
+			);
 		},
 	});
 
@@ -137,14 +152,22 @@ export default function cavemanExtension(pi: ExtensionAPI) {
 		if (event.source !== "extension") {
 			const text = (event.text ?? "").trim();
 			if (DEACTIVATION_RE.test(text)) {
-				if (mode !== "off") persistMode("off", ctx);
+				if (mode !== "off") {
+					persistMode("off", ctx);
+					saveProjectMode(ctx.cwd, "off");
+				}
 			} else if (mode === "off" && ACTIVATION_RE.test(text)) {
 				persistMode("full", ctx);
+				saveProjectMode(ctx.cwd, "full");
 			}
 		}
 		return { action: "continue" as const };
 	});
 
+	pi.on("turn_end", (_event, ctx) => {
+		setStatus(ctx);
+	});
+
 	pi.on("before_agent_start", (event) => {
 		if (mode === "off") return undefined;
 		return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kulapard/pi-caveman",
-  "version": "0.4.2",
+  "version": "0.5.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>