@kulapard/pi-caveman 0.3.0 → 0.4.1

package/AGENTS.md

@@ -30,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,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-06-29
+
+### Changed
+
+- README install instructions now recommend `pi install
+  https://github.com/kulapard/pi-caveman` as the primary direct-load method,
+  keeping `pi -e` documented as a per-session fallback.
+
+### Added
+
+- Guard tests for `caveman-compress` backup rules, the GitHub install URL in
+  the root README, and the `caveman` skill's delegation to `caveman-commit` /
+  `caveman-review`.
+
+## [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
@@ -65,7 +104,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.3.0...HEAD
+[Unreleased]: https://github.com/kulapard/pi-caveman/compare/v0.4.1...HEAD
+[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
 [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

@@ -20,13 +20,23 @@ Install it into a Pi setup with:
 pi install npm:@kulapard/pi-caveman
 ```
 
-You can also load it straight from a checkout on disk (no install needed) — see
-the `pi -e` mechanism below.
+You can also load it straight from a checkout on disk — see the `pi -e`
+mechanism below.
 
-### Load the extension directly (confirmed mechanism)
+### Install from GitHub
 
-The simplest, confirmed way to load it is Pi's `-e` flag, which loads the
-extension file for a session:
+The simplest way to load the latest version directly from the repository is:
+
+```bash
+pi install https://github.com/kulapard/pi-caveman
+```
+
+Pi resolves the `pi` block in `package.json` and loads both the extension and
+all skills from the cloned directory.
+
+### Load the extension directly (per-session)
+
+For quick testing without installing, use Pi's `-e` flag for a single session:
 
 ```bash
 pi -e /path/to/pi-caveman/extensions/caveman.ts --skill /path/to/pi-caveman/skills

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kulapard/pi-caveman",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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",
@@ -45,7 +45,8 @@
     "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",

package/skills/caveman/SKILL.md

@@ -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

@@ -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