@evref-bl/pharo-mcp 3.4.0 → 3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-mcp",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Pharo MCP agent-host templates",
   "license": "MIT",
   "type": "module",

package/templates/pharo-skills/pharo-image-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pharo-image-sync
-description: Move code between a live Pharo image and its Tonel files, and tell the two apart. Use before exporting image changes, after a checkout moves under the image, and whenever Iceberg, the image and the files disagree.
+description: Move code between a live Pharo image and its Tonel files, and tell the two apart. Use before exporting image changes, after a checkout moves under the image, before saying what is or is not committed, and whenever Iceberg, the image and the files disagree.
 ---
 
 # Pharo Image Sync
@@ -12,6 +12,27 @@ Iceberg diff does not mean anything was written to disk.
 Git itself is ordinary shell work. These tools only cross the boundary between
 the image and the files.
 
+## What Is Committed
+
+The user may commit through Iceberg at any time, and nothing tells you. What
+you remember changing is not evidence that it is uncommitted, so ask before
+calling anything unsaved or at risk.
+
+- `git log` in the checkout says what was committed. Iceberg commits are
+  ordinary git commits, so it answers even when the image does not.
+- `repository_search` with `isModified` names the repositories and packages
+  Iceberg marks as changed since they were last written. A mark says where to
+  look, not that something differs: an edit that was undone, or a test that
+  compiled and removed a method, leaves one too.
+- `repository_change_list` compares a repository's marked packages with its
+  files and names those that really differ, and the files git sees changed.
+  Anything not committed is in one of them.
+- To know whether one change is committed, compare `method_get` with the
+  class's file at `HEAD` (`git show HEAD:<path>`).
+
+`git status` cannot answer for the image: Iceberg writes files only when it
+commits or exports, so the checkout stays clean while the image holds changes.
+
 ## Out Of The Image
 
 1. Verify which repository you are about to write to: `repository_search` for

package/templates/pharo-skills/pharo-mcp-recovery/SKILL.md

@@ -11,7 +11,8 @@ standalone image without a safer environment-specific recovery surface.
 ## Workflow
 
 1. Determine whether the failure is the client route, MCP server, image, or
-   process.
+   process. A client that cannot reach the server says nothing yet about the
+   image.
 2. Preserve the image, changes, sources, VM logs, launch command, MCP URL, and
    repository/Git facts before mutation.
 3. Restart the same image first. Inspect `isRunning`, `isListening`, and
@@ -19,7 +20,10 @@ standalone image without a safer environment-specific recovery surface.
 4. Create a replacement image only after preserving the original. Use
    `pharo-project-load` to restore MCP and the target project.
 5. Recover changes by inspecting Epicea history before confirmed application.
-   Use `pharo-image-sync` before repository attachment or Tonel export.
+   History lists every change since the image started, committed or not:
+   check a change against the checkout's `git log` before naming it as lost,
+   as `pharo-image-sync` says. Use it too before repository attachment or
+   Tonel export.
 6. Verify the recovered behavior with focused inspection or tests.
 
 ## Stop And Ask

package/templates/pharo.AGENTS.md

@@ -1,48 +1,40 @@
 # Pharo MCP Agent Guide
 
-Use the configured `pharo` MCP server whenever a task depends on the running
-image. Preserve unrelated changes, and say which live check you could not run
-rather than letting source stand in for it.
+Use the `pharo` MCP server whenever a task depends on the running image.
+Preserve unrelated changes, and say which live check you could not run rather
+than letting source stand in for it.
 
 ## Read First
 
-- Inspect the tools and schemas exposed by the current client; do not rely on
-  remembered names. `tool_search` finds what is not advertised, and `tool_get`
-  answers one tool's schema.
-- Prefer the least-mutating dedicated tool. Use `image_evaluate` only when no
-  dedicated tool fits.
-- Treat image, Tonel, Iceberg, and Git state as separate. None of them proves
-  anything about the others.
-- The image is one workspace. It has no branches and no worktrees, so two
-  agents working in it at once share every edit, and one export writes both
-  their changes into one diff. One writer at a time.
-- Tools change the running image but never save it; use a safe image boundary.
+- Look tools up rather than recall them: `tool_search` finds what the image
+  does not advertise, `tool_get` gives a tool's schema.
+- Prefer the least-mutating dedicated tool; `image_evaluate` only when none
+  fits.
+- Image, Tonel, Iceberg and Git are separate states; none proves anything
+  about another.
+- An image takes one writer: it has no branches, so two agents in it share
+  every edit.
+- Tools never save the image.
+- The user may commit through Iceberg unseen: ask the image and the checkout
+  before calling any work uncommitted.
 
 ## Context Loading
 
-- Before Pharo source changes: read the project's Pharo coding and testing
-  guidance. If none exists, use the local
-  [Pharo coding](pharo-references/pharo-coding.md) reference.
-- Before reading an answer closely, rewriting methods, or acting on a warning a
-  call came back with: read
+- Changing Pharo code: the project's coding guidance, or else
+  [Pharo coding](pharo-references/pharo-coding.md).
+- Reading an answer closely, rewriting methods, or acting on a warning:
   [tool reference](pharo-references/tool-reference.md).
-- Before loading a project: use `skills/pharo-project-load/SKILL.md`.
-- Before moving code between the image and its files: use
+- Loading a project: `skills/pharo-project-load/SKILL.md`.
+- Moving code between the image and its files, or saying what is committed:
   `skills/pharo-image-sync/SKILL.md`.
-- Before reproducing smalltalkCI or GitHub failures: use
-  `skills/pharo-ci-repro/SKILL.md`.
-- Before profiling or optimizing Pharo code: use
-  `skills/pharo-code-profiling/SKILL.md`.
-- Before recovering a stopped standalone image: use
-  `skills/pharo-mcp-recovery/SKILL.md`.
+- Reproducing smalltalkCI or GitHub failures: `skills/pharo-ci-repro/SKILL.md`.
+- Profiling: `skills/pharo-code-profiling/SKILL.md`.
+- Recovering a stopped standalone image: `skills/pharo-mcp-recovery/SKILL.md`.
 
 ## Workflow
 
-1. Discover the exact tool and inspect the target with read-only calls.
-2. Preview or verify identity before risky mutation.
-3. Make the narrowest image-side change.
-4. Run focused SUnit tests and inspect the result.
-5. Use the image-sync skill before exporting or committing Tonel changes.
-
-For repository work, verify repository identity before mutation and inspect the
-image-side diff before export or commit.
+1. Inspect with read-only calls.
+2. Verify identity before a risky change.
+3. Make the narrowest change in the image.
+4. Run focused tests.
+5. Use the image-sync skill before exporting or committing.