@kulapard/pi-caveman 0.2.0 → 0.4.0

package/AGENTS.md

@@ -12,6 +12,12 @@ Project memory for agents working in this repo. Non-obvious conventions only.
   session always starts `off`. There is **no** cross-session config file or env var.
 - Activation = `before_agent_start` appends `modeInstructions(mode)` to the
   system prompt. Statusline = `ctx.ui.setStatus("caveman", …)` guarded by `hasUI`.
+- The extension's `modeInstructions` injection is the **canonical** activator;
+  the `caveman` skill (`skills/caveman/SKILL.md`) is a standalone fallback for
+  hosts that load skills but not this extension. When both are active the model
+  may see both rule sets — mild, intentional redundancy. They are not
+  programmatically de-duped: skill loading is model-driven and the skill's prose
+  differs from `modeInstructions`, so there is no reliable text to match on.
 - Pi 0.80.2 has **no `agents/` subagent mechanism**. The `agents/cavecrew-*.md`
   files are reference personas only and cavecrew is optional/out-of-scope.
 
@@ -24,12 +30,18 @@ Project memory for agents working in this repo. Non-obvious conventions only.
 - **Verbatim preservation**: caveman-compress never alters code blocks, inline
   code, URLs, file paths, commands, or exact error strings. The skill instructs
   the agent to self-validate these against the original and, on any mismatch it
-  cannot fix, restore from the `.original` backup rather than leave a corrupted file.
+  cannot fix, restore from the `.original` backup that was created during the
+  same invocation (stale backups are rejected before compression starts).
 - `caveman-compress` is **prompt-only**: the Pi agent performs the compression
   with its own model and file tools, driven by `SKILL.md`. There is no Python and
   no external model CLI; coverage is the doc-guard test `tests/compress-docs.test.mjs`.
 
-## Tests / validation
+## Changelog
+
+Every notable change must update `CHANGELOG.md` under `[Unreleased]`. Before
+finishing a task, run `npm run changelog:check` to confirm the changelog was
+updated for the files you changed. CI also runs this check on every pull
+request.
 
 - `npm test` runs `pretest` (`npm run typecheck` → `tsc --noEmit`) first, then the
   `node --test` suites under `tests/`. Typecheck failures fail the test run.

package/CHANGELOG.md

@@ -7,6 +7,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-06-29
+
+### Fixed
+
+- `caveman-compress` no longer restores from a potentially stale `.original`
+  backup on validation failure; it now aborts if a backup already exists and
+  only restores from the backup created during the same invocation.
+- `caveman-compress` README clarified: users should edit the source file and
+  remove/rename the old `.original` backup before re-compressing; extensionless
+  files now have an explicit `.original` backup rule.
+- Extension command handler tests now `await` async handlers, preventing false
+  greens if handlers become asynchronous.
+
+### Changed
+
+- Workflow test now matches the actual `run: npm publish` step instead of any
+  `npm publish` substring.
+
+### Added
+
+- `scripts/check-changelog.mjs` and a CI check (`npm run changelog:check`)
+  enforce that `CHANGELOG.md` is updated for any notable file change; the
+  project convention also instructs agents to update the changelog under
+  `[Unreleased]`.
+
+## [0.3.0] - 2026-06-29
+
+### Fixed
+
+- `/caveman-help` card linked "Full docs" to the upstream `JuliusBrussee/caveman`
+  repo; now points to `kulapard/pi-caveman`.
+- `caveman-help` skill table was missing `/caveman-stats`, disagreeing with the
+  extension's own `HELP_TEXT`; added the row.
+- `ultra` mode was documented as "Tables over prose" in the README and help
+  card, contradicting the injected mode instructions; docs now match behavior
+  (abbreviate prose words, arrows for causality).
+- Input handler no longer throws when an input event arrives without `text`
+  (`event.text.trim()` → `(event.text ?? "").trim()`).
+- `caveman-compress` docs said the backup is always `FILE.original.md`, but the
+  skill preserves the source extension; corrected to `FILE.original.<ext>`.
+
+### Changed
+
+- `engines.node` floor raised from `>=18` to `>=22.6.0`, matching the
+  `node --experimental-strip-types` requirement of the test/typecheck workflow.
+- Natural-language activation now also triggers on `"be brief"` (added to
+  `ACTIVATION_RE`, the `caveman` skill description, and the README) so the
+  deterministic regex matches the advertised triggers.
+
 ## [0.2.0] - 2026-06-29
 
 ### Changed
@@ -41,6 +90,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.2.0...HEAD
+[Unreleased]: https://github.com/kulapard/pi-caveman/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/kulapard/pi-caveman/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/kulapard/pi-caveman/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/kulapard/pi-caveman/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/kulapard/pi-caveman/releases/tag/v0.1.0

package/README.md

@@ -12,9 +12,9 @@ plus a set of skills under `skills/`.
 
 ## Install
 
-pi-caveman publishes to npm as
+pi-caveman is published to npm as
 [`@kulapard/pi-caveman`](https://www.npmjs.com/package/@kulapard/pi-caveman).
-Once the first release is live, install it into a Pi setup with:
+Install it into a Pi setup with:
 
 ```bash
 pi install npm:@kulapard/pi-caveman
@@ -67,7 +67,7 @@ session ends.
 |------|---------|--------|
 | **lite** | `/caveman lite` | Drop filler. Keep sentence structure. |
 | **full** | `/caveman` | Drop articles, filler, pleasantries, hedging. Fragments OK. Default. |
-| **ultra** | `/caveman ultra` | Extreme compression. Bare fragments. Tables over prose. |
+| **ultra** | `/caveman ultra` | Extreme compression. Bare fragments. Abbreviate prose words; arrows (X → Y). |
 | **wenyan-lite** | `/caveman wenyan-lite` | Classical Chinese (文言文) style, light compression. |
 | **wenyan-full** | `/caveman wenyan` | Full 文言文. Maximum classical terseness. |
 | **wenyan-ultra** | `/caveman wenyan-ultra` | Extreme classical terseness. |
@@ -91,7 +91,7 @@ You don't have to use a slash command. The extension watches your messages and
 switches mode on phrases like:
 
 - **Activate:** "caveman mode", "talk like caveman", "use caveman", "less
-  tokens", "fewer tokens", "save tokens" → enables **full** mode.
+  tokens", "fewer tokens", "save tokens", "be brief" → enables **full** mode.
 - **Deactivate:** "stop caveman", "normal mode", "disable caveman" → turns it
   off.
 
@@ -118,7 +118,7 @@ package — so it does not belong in this extension-plus-skills package.
 
 The Pi-side equivalent is the `caveman-compress` skill, invoked via the
 `/caveman-compress` command. It is prompt-only: the Pi agent itself compresses a
-prose memory file in place (writing a `FILE.original.md` backup) using its own
+prose memory file in place (writing a `FILE.original.<ext>` backup) using its own
 model and file tools, preserving code, URLs, and paths verbatim. No Python and no
 external Claude CLI are involved — compression is performed by the host Pi agent,
 the same way the other skills work.

package/extensions/caveman-core.ts

@@ -90,5 +90,5 @@ Auto-clarity:
 }
 
 export const ACTIVATION_RE =
-	/\b(caveman mode|talk like caveman|use caveman|less tokens|fewer tokens|save tokens)\b/i;
+	/\b(caveman mode|talk like caveman|use caveman|less tokens|fewer tokens|save tokens|be brief)\b/i;
 export const DEACTIVATION_RE = /\b(stop caveman|normal mode|disable caveman)\b/i;

package/extensions/caveman.ts

@@ -133,15 +133,14 @@ export default function cavemanExtension(pi: ExtensionAPI) {
 	});
 
 	pi.on("input", (event, ctx) => {
-		if (event.source === "extension") return { action: "continue" as const };
-		const text = event.text.trim();
-		if (DEACTIVATION_RE.test(text)) {
-			if (mode !== "off") persistMode("off", ctx);
-			return { action: "continue" as const };
-		}
-		if (mode === "off" && ACTIVATION_RE.test(text)) {
-			persistMode("full", ctx);
-			return { action: "continue" as const };
+		// Ignore the extension's own echoed input (self-echo guard).
+		if (event.source !== "extension") {
+			const text = (event.text ?? "").trim();
+			if (DEACTIVATION_RE.test(text)) {
+				if (mode !== "off") persistMode("off", ctx);
+			} else if (mode === "off" && ACTIVATION_RE.test(text)) {
+				persistMode("full", ctx);
+			}
 		}
 		return { action: "continue" as const };
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kulapard/pi-caveman",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -23,7 +23,7 @@
     "CHANGELOG.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.6.0"
   },
   "keywords": [
     "pi-package",
@@ -45,10 +45,11 @@
     "pretest": "npm run typecheck",
     "test": "node --experimental-strip-types --test tests/**/*.test.mjs",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "changelog:check": "node scripts/check-changelog.mjs --base origin/master"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.2",
-    "typescript": "^5"
+    "typescript": "^6"
   }
 }

package/skills/caveman/SKILL.md

@@ -5,7 +5,7 @@ description: >
   while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra,
   wenyan-lite, wenyan-full, wenyan-ultra.
   Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens",
-  "be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.
+  "fewer tokens", "save tokens", "be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.
 ---
 
 Respond terse like smart caveman. All technical substance stay. Only fluff die.
@@ -41,6 +41,7 @@ Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
 | **wenyan-ultra** | Extreme abbreviation while keeping classical Chinese feel. Maximum compression, ultra terse |
 
 Example — "Why React component re-render?"
+
 - lite: "Your component re-renders because you create a new object reference each render. Wrap it in `useMemo`."
 - full: "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
 - ultra: "Inline obj prop → new ref → re-render. `useMemo`."
@@ -49,6 +50,7 @@ Example — "Why React component re-render?"
 - wenyan-ultra: "新參照→重繪。useMemo Wrap。"
 
 Example — "Explain database connection pooling."
+
 - lite: "Connection pooling reuses open connections instead of creating new ones per request. Avoids repeated handshake overhead."
 - full: "Pool reuse open DB connections. No new connection per request. Skip handshake overhead."
 - ultra: "Pool = reuse DB conn. Skip handshake → fast under load."
@@ -58,6 +60,7 @@ Example — "Explain database connection pooling."
 ## Auto-Clarity
 
 Drop caveman when:
+
 - Security warnings
 - Irreversible action confirmations
 - Multi-step sequences where fragment order or omitted conjunctions risk misread
@@ -68,11 +71,15 @@ Resume caveman after clear part done.
 
 Example — destructive op:
 > **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
+>
 > ```sql
 > DROP TABLE users;
 > ```
+>
 > Caveman resume. Verify backup exist first.
 
 ## Boundaries
 
-Code/commits/PRs: write normal. "stop caveman" or "normal mode": revert. Level persist until changed or session end.
+Code explanations / architecture discussion: write normal. "stop caveman" or "normal mode": revert. Level persist until changed or session end.
+
+Note: when the user asks for a commit message, use `caveman-commit`. When asked to review a diff/PR, use `caveman-review`. Those skills override this line for their specific output.

package/skills/caveman-compress/README.md

@@ -22,10 +22,10 @@ The agent reads its memory file (`AGENTS.md` / `CLAUDE.md`) on every session sta
 
 ```
 AGENTS.md          ← compressed (the agent reads this — fewer tokens every session)
-AGENTS.original.md ← human-readable backup (you edit this)
+AGENTS.original.md ← human-readable backup (snapshot taken at first compression)
 ```
 
-Original never lost. You can read and edit `.original.md`. Run skill again to re-compress after edits.
+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.
 
 ## Benchmarks
 
@@ -81,6 +81,7 @@ its own model and file tools — there is no separate tool or language to instal
 ```
 
 Examples:
+
 ```
 /caveman-compress AGENTS.md
 /caveman-compress CLAUDE.md
@@ -96,6 +97,7 @@ Examples:
 | Extensionless natural language | ✅ Yes |
 | `.py`, `.js`, `.ts`, `.json`, `.yaml` | ❌ Skip (code/config) |
 | `*.original.md` | ❌ Skip (backup files) |
+| `*.original` (extensionless) | ❌ Skip (backup files) |
 
 ## How It Work
 
@@ -104,15 +106,20 @@ Examples:
         ↓
 agent detects file type      (prose? else skip)
         ↓
-agent backs up original  →  AGENTS.original.md   (verbatim, never overwritten)
+agent checks for existing backup  →  abort if stale `.original` exists
+        ↓
+agent backs up original once  →  AGENTS.original.md   (verbatim snapshot)
         ↓
 agent rewrites prose to caveman, code/URLs/paths left exact
         ↓
 agent self-validates: protected tokens byte-identical to original
         ↓
-if a protected token changed: fix it, or restore from backup and report
+if a protected token changed: fix it, or restore from the just-created backup and report
         ↓
 write compressed  →  AGENTS.md
+
+To re-compress, edit `AGENTS.md`, then remove/rename the old `AGENTS.original.md`
+so the skill can create a fresh snapshot.
 ```
 
 The agent does this with its own model and file tools — no external CLI, no separate runtime.

package/skills/caveman-compress/SKILL.md

@@ -3,7 +3,7 @@ name: caveman-compress
 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.md.
+  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"
 ---
 
@@ -11,7 +11,7 @@ description: >
 
 ## Purpose
 
-Compress natural language files (`AGENTS.md`, `CLAUDE.md`, todos, preferences) into caveman-speak to reduce input tokens. Compressed version overwrites original. Human-readable backup saved as `<filename>.original.md`.
+Compress natural language files (`AGENTS.md`, `CLAUDE.md`, todos, preferences) into caveman-speak to reduce input tokens. Compressed version overwrites original. Human-readable backup saved as `<filename>.original.<ext>` (same extension as the source, e.g. `AGENTS.md` → `AGENTS.original.md`, `notes.txt` → `notes.original.txt`).
 
 ## Trigger
 
@@ -21,12 +21,12 @@ Compress natural language files (`AGENTS.md`, `CLAUDE.md`, todos, preferences) i
 
 You (the Pi agent) perform the compression directly — there is no separate tool to run. Given `/caveman-compress <filepath>`:
 
-1. **Skip backups.** If the path ends in `.original.<ext>` (e.g. `AGENTS.original.md`), stop — never compress a backup file.
+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.** Write a verbatim copy to `<filename>.original.<ext>` (e.g. `AGENTS.md` → `AGENTS.original.md`), **only if that backup does not already exist** — never overwrite an existing `.original` backup.
+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.
 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 `.original` backup and report the failure rather than leave a corrupted file.
+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.
 
 Only the rewrite needs the model (you); detection, backup, and validation are mechanical.
@@ -34,6 +34,7 @@ Only the rewrite needs the model (you); detection, backup, and validation are me
 ## Compression Rules
 
 ### Remove
+
 - Articles: a, an, the
 - Filler: just, really, basically, actually, simply, essentially, generally
 - Pleasantries: "sure", "certainly", "of course", "happy to", "I'd recommend"
@@ -42,6 +43,7 @@ Only the rewrite needs the model (you); detection, backup, and validation are me
 - Connective fluff: "however", "furthermore", "additionally", "in addition"
 
 ### Preserve EXACTLY (never modify)
+
 - Code blocks (fenced ``` and indented)
 - Inline code (`backtick content`)
 - URLs and links (full URLs, markdown links)
@@ -53,6 +55,7 @@ Only the rewrite needs the model (you); detection, backup, and validation are me
 - Environment variables (`$HOME`, `NODE_ENV`)
 
 ### Preserve Structure
+
 - All markdown headings (keep exact heading text, compress body below)
 - Bullet point hierarchy (keep nesting level)
 - Numbered lists (keep numbering)
@@ -60,6 +63,7 @@ Only the rewrite needs the model (you); detection, backup, and validation are me
 - Frontmatter/YAML headers in markdown files
 
 ### Compress
+
 - Use short synonyms: "big" not "extensive", "fix" not "implement a solution for", "use" not "utilize"
 - Fragments OK: "Run tests before commit" not "You should always run tests before committing"
 - Drop "you should", "make sure to", "remember to" — just state the action
@@ -69,6 +73,7 @@ Only the rewrite needs the model (you); detection, backup, and validation are me
 CRITICAL RULE:
 Anything inside ``` ... ``` must be copied EXACTLY.
 Do not:
+
 - remove comments
 - remove spacing
 - reorder lines
@@ -79,6 +84,7 @@ Inline code (`...`) must be preserved EXACTLY.
 Do not modify anything inside backticks.
 
 If file contains code blocks:
+
 - Treat code blocks as read-only regions
 - Only compress text outside them
 - Do not merge sections around code
@@ -104,5 +110,5 @@ Compressed:
 - Skip files larger than ~500 KB (too big to rewrite safely in one pass)
 - If file has mixed content (prose + code), compress ONLY the prose sections
 - If unsure whether something is code or prose, leave it unchanged
-- Original file is backed up as FILE.original.md before overwriting
-- Never compress FILE.original.md (skip it)
+- Original file is backed up as FILE.original.<ext> (same extension as the source) before overwriting
+- Never compress a FILE.original.<ext> backup (skip it)

package/skills/caveman-help/SKILL.md

@@ -16,7 +16,7 @@ Display this reference card when invoked. One-shot — do NOT change mode, write
 |------|---------|-------------|
 | **Lite** | `/caveman lite` | Drop filler. Keep sentence structure. |
 | **Full** | `/caveman` | Drop articles, filler, pleasantries, hedging. Fragments OK. Default. |
-| **Ultra** | `/caveman ultra` | Extreme compression. Bare fragments. Tables over prose. |
+| **Ultra** | `/caveman ultra` | Extreme compression. Bare fragments. Abbreviate prose words; arrows (X → Y). |
 | **Wenyan-Lite** | `/caveman wenyan-lite` | Classical Chinese style, light compression. |
 | **Wenyan-Full** | `/caveman wenyan` | Full 文言文. Maximum classical terseness. |
 | **Wenyan-Ultra** | `/caveman wenyan-ultra` | Extreme. Ancient scholar on a budget. |
@@ -30,6 +30,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-stats** | `/caveman-stats` | On-demand, model-driven estimate of tokens saved this session. |
 | **caveman-help** | `/caveman-help` | This card. |
 
 ## Deactivate
@@ -48,4 +49,4 @@ Mode set per session. New session start → mode `off`; activate again with `/ca
 
 ## More
 
-Full docs: https://github.com/JuliusBrussee/caveman
+Full docs: https://github.com/kulapard/pi-caveman