@ponythewhite/base-context 1.0.6 → 1.0.8

package/dist/skills/skill-creator/SKILL.md

@@ -14,9 +14,26 @@ A skill is a directory with a `SKILL.md` file (YAML frontmatter + markdown instr
 
 Before writing a Python-backed skill, read [references/python-skills.md](references/python-skills.md) for the package contract.
 
+## Small Reusable Helpers
+
+Keep a one-off operation inline. For repeated multi-step work, first write an
+ordinary named function with explicit inputs and a result docstring. Read current
+data on each call; do not capture old answers, open handles or hidden REPL state.
+After two useful occurrences across tasks, or an explicit reuse request, save an
+editable `scripts/<name>.py` and a short project `SKILL.md` with the existing name,
+description and invocation conventions. A small helper does not need a Python
+package, `pyproject.toml`, installation or promotion workflow.
+
+After edits, execute the updated definition or invoke the saved script afresh
+(for example with `runpy.run_path` in the selected environment). Discover through
+the short description and load code only when needed. Prefer the standard library
+and existing dependencies; no per-call installation or automatic scheduling.
+Ordinary errors remain ordinary tool results. Existing execution permissions and
+native instruction-epoch rules still apply.
+
 ## Creating a Skill
 
-1. **Pick the kind.** Default to markdown. Go Python only when the agent should *call* the capability (`await my_skill(...)`) instead of following instructions.
+1. **Pick the kind.** Default to markdown, including small editable Python scripts. Use a Python-backed package when the capability needs an installed module such as `await my_skill(...)`, not just an ordinary helper function.
 2. **Pick the location.** Ask the user when it is not obvious from context:
    - Project skill, shared via the repo: `.base-context/skills/<name>/`
    - Personal global skill: `~/.base-context/skills/<name>/`, or `$BASE_CONTEXT_HOME/skills/<name>/` when configured

package/docs/settings.md

@@ -454,6 +454,51 @@ records its first actual native compatibility contract once before sending. This
 does not select a new view or authorize missing contracts in legacy history. Off
 is not the independent upstream H benchmark control.
 
+### Scoped error-fix notes
+
+| Setting | Type | Default | Description |
+| --- | --- | --- | --- |
+| `learning.enabled` | boolean | `false` | Let the active agent save and retrieve small scoped problem/fix notes |
+
+This opt-in is separate from automatic refinement. It adds no reviewer or model
+call. After a useful recurring repair reaches normal task success, or after an
+explicit user correction, the agent can upsert a memory with an `error-fix:` key.
+Notes are advice, not policy. The current task and observations take precedence.
+
+Workspace notes use the selected project root's `.base-context/harness-state.json`.
+They are not retrieved in a different workspace. Existing session/global paths
+and `harness_state.json` filenames stay unchanged. Explicit CRUD stays available
+when learning is off:
+
+```python
+notes = rlm.get_harness_state(scope="workspace")
+notes.upsert("memory", "Project tests", "Problem: dependency missing. Fix: use .venv/bin/python.",
+             id="error-fix:project-tests",
+             metadata={"tool": "ipython", "operation": "project tests", "condition": "Dependencies are in this project's .venv"})
+notes.get("memory", "error-fix:project-tests")
+# After the note becomes obsolete:
+notes.delete_memory("error-fix:project-tests")
+```
+
+Use local scope for session-only notes. Global writes require an explicit global
+action. Workspace resolution uses the session owner's selected root, never a
+changed REPL working directory. Missing workspace support does not redirect a
+write to another project. Scope-prefixed IDs such as
+`workspace:error-fix:project-tests` work with ordinary inspect/edit/delete calls.
+
+Retrieval requires an exact available-tool name when specified and positive word
+overlap with the current operation or task goal. Known conflicting environment
+versions omit a note; retrieval never probes the environment. At most three
+whole notes fit a 512-unit local text allowance, including their advice wrapper.
+The default conservative request-meter estimate charges one unit per UTF-8 byte;
+it is not an exact provider chat/template token count. No remote count call is
+made for notes. Unchanged advice omits version/timestamp/use bookkeeping.
+
+Do not record cancellation, deliberately failing tests, transient rate limits,
+secrets, tracebacks, or permanent command bans. Correct old notes with ordinary
+edit/delete. The existing file owner and atomic save apply; independently running
+writers do not gain lossless multi-process transactions.
+
 ### Automatic refinement
 
 | Setting | Type | Default | Description |

package/docs/skills.md

@@ -11,6 +11,7 @@ Base Context implements the [Agent Skills standard](https://agentskills.io/speci
 - [Locations](#locations)
 - [Built-in Skills](#built-in-skills)
 - [How Skills Work](#how-skills-work)
+- [Reusable Helpers Without Packaging](#reusable-helpers-without-packaging)
 - [Python-Backed Skills](#python-backed-skills)
 - [Creating Skills with Base Context](#creating-skills-with-base-context)
 - [Skill Commands](#skill-commands)
@@ -152,6 +153,80 @@ Generic non-native behavior is unchanged.
 
 Skills with `disable-model-invocation: true` are hidden from the startup skill list. They can still be invoked explicitly with `/skill:name`.
 
+## Reusable Helpers Without Packaging
+
+For repeated multi-step work, start with an ordinary named Python function in
+`ipython`. Keep one-off operations inline and prefer an existing project command
+when it already does the work. Give changing paths, selectors, output paths and
+options explicit parameters. Reuse the code, not its previous answer: read current
+inputs on every call. Do not capture an open handle or hidden mutable REPL state.
+
+After two useful occurrences across tasks, or an explicit request for reuse, save
+the function in an editable `.py` file with a short project markdown skill. This
+is a practical heuristic, not a repetition detector. A small helper needs no
+`pyproject.toml`, package installation, manifest or promotion step. Use the standard
+library and dependencies already available in the selected environment.
+
+For example, save `scripts/matching_lines.py` in
+`.base-context/skills/matching-lines/`:
+
+```python
+from pathlib import Path
+
+
+def matching_lines(path: str, needle: str, limit: int = 20) -> list[tuple[int, str]]:
+    """Read a current UTF-8 file; return literal matches with one-based lines."""
+    if limit < 1:
+        raise ValueError("limit must be positive")
+    matches = []
+    with Path(path).open(encoding="utf-8") as source:
+        for line_number, line in enumerate(source, start=1):
+            if needle in line:
+                matches.append((line_number, line.rstrip("\r\n")))
+                if len(matches) == limit:
+                    break
+    return matches
+```
+
+Add the ordinary `SKILL.md` next to `scripts/`:
+
+```markdown
+---
+name: matching-lines
+description: Read current UTF-8 files for repeated literal line lookups. Inputs are path, needle and limit; output is a list of one-based line numbers and text.
+---
+Load scripts/matching_lines.py afresh with runpy.run_path, then call
+matching_lines(path, needle, limit=20). Resolve the script path against this
+skill directory. No matches returns an empty list; ordinary errors propagate.
+```
+
+Only the short skill description enters discovery. Load the instructions and code
+when the active task needs them. For this standard-library helper, a fresh load
+and call in `ipython` can be:
+
+```python
+from runpy import run_path
+
+matching_lines = run_path("/repo/.base-context/skills/matching-lines/scripts/matching_lines.py")["matching_lines"]
+matches = matching_lines("/repo/current.txt", "needle", limit=20)
+```
+
+After editing a loaded helper, execute its updated definition before calling it
+again, or load the saved script afresh as above. For project imports or commands,
+use the project's own environment instead of installing them into the kernel.
+Fresh execution of editable code does not replace the captured instruction body
+of an active native skill epoch.
+
+Saving a helper does not schedule or authorize execution. Invocation still needs
+the normal model/tool decision or an explicit user workflow, under the existing
+permissions. Do not add an import manager, dependency snapshots or per-call setup.
+
+For a useful comparison, include construction and failed attempts, then compare
+1, 2 and 5 uses with the direct path. Record construction time/tokens, later
+model/tool calls and total sequence cost; report time and money separately. A
+first use is not free warmup. Keep the direct path when saving and finding the
+helper costs more than it saves.
+
 ## Python-Backed Skills
 
 A Python-backed skill uses the same `SKILL.md` metadata and invocation behavior as a markdown skill, but also provides a Python package for the Python kernel.
@@ -242,7 +317,7 @@ To force the creation workflow explicitly, invoke the built-in skill command:
 Tell the agent three things:
 
 1. **Scope:** use `.base-context/skills/<name>/` for a project skill committed with the repository, or `~/.base-context/skills/<name>/` for a personal skill.
-2. **Kind:** ask for a markdown skill when the capability is primarily instructions; ask for a Python-backed skill when the agent should call reusable functionality from the Python REPL.
+2. **Kind:** use a markdown skill with editable scripts for small reusable helpers. Ask for a Python-backed skill when an installed module and its package dependencies are needed.
 3. **Contract:** describe the intended Python call, inputs, output, dependencies, credentials, and verification behavior.
 
 The agent should create `SKILL.md` in both cases. For a Python-backed skill it should also create `pyproject.toml` and `src/<import_name>/__init__.py`, expose a documented callable, and verify that the package imports in the kernel.
@@ -251,7 +326,7 @@ Use `/reload` to rediscover new or edited skill metadata. Start a fresh Base Con
 
 ### Installed Skills and Continual Harness Skills
 
-An installed Python-backed skill is a real package on disk that adds executable functionality to the kernel. A continual harness skill entry is a persisted description of a reusable Python call, including its reference and argument contract. `/refine` can create or update the latter after a repeated procedure emerges, but it does not replace packaging new functionality with `skill-creator`.
+An installed Python-backed skill is a real package on disk that adds executable functionality to the kernel. A continual harness skill entry is a persisted description of a reusable Python call, including its reference and argument contract. `/refine` can create or update the latter after a repeated procedure emerges, but a description does not create executable code. Small helpers can use the editable script and markdown-skill path above; an installed package is optional.
 
 ## Skill Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ponythewhite/base-context",
-	"version": "1.0.6",
+	"version": "1.0.8",
 	"description": "Synerise base-context: a coding and research agent with durable context and a persistent Python REPL",
 	"type": "module",
 	"bin": {
@@ -42,9 +42,9 @@
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "^1.3.0",
-		"@ponythewhite/base-context-agent": "1.0.6",
-		"@ponythewhite/base-context-ai": "1.0.6",
-		"@ponythewhite/base-context-tui": "1.0.6",
+		"@ponythewhite/base-context-agent": "1.0.8",
+		"@ponythewhite/base-context-ai": "1.0.8",
+		"@ponythewhite/base-context-tui": "1.0.8",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"chalk": "^5.5.0",
 		"cli-highlight": "^2.1.11",

package/skills/skill-creator/SKILL.md

@@ -14,9 +14,26 @@ A skill is a directory with a `SKILL.md` file (YAML frontmatter + markdown instr
 
 Before writing a Python-backed skill, read [references/python-skills.md](references/python-skills.md) for the package contract.
 
+## Small Reusable Helpers
+
+Keep a one-off operation inline. For repeated multi-step work, first write an
+ordinary named function with explicit inputs and a result docstring. Read current
+data on each call; do not capture old answers, open handles or hidden REPL state.
+After two useful occurrences across tasks, or an explicit reuse request, save an
+editable `scripts/<name>.py` and a short project `SKILL.md` with the existing name,
+description and invocation conventions. A small helper does not need a Python
+package, `pyproject.toml`, installation or promotion workflow.
+
+After edits, execute the updated definition or invoke the saved script afresh
+(for example with `runpy.run_path` in the selected environment). Discover through
+the short description and load code only when needed. Prefer the standard library
+and existing dependencies; no per-call installation or automatic scheduling.
+Ordinary errors remain ordinary tool results. Existing execution permissions and
+native instruction-epoch rules still apply.
+
 ## Creating a Skill
 
-1. **Pick the kind.** Default to markdown. Go Python only when the agent should *call* the capability (`await my_skill(...)`) instead of following instructions.
+1. **Pick the kind.** Default to markdown, including small editable Python scripts. Use a Python-backed package when the capability needs an installed module such as `await my_skill(...)`, not just an ordinary helper function.
 2. **Pick the location.** Ask the user when it is not obvious from context:
    - Project skill, shared via the repo: `.base-context/skills/<name>/`
    - Personal global skill: `~/.base-context/skills/<name>/`, or `$BASE_CONTEXT_HOME/skills/<name>/` when configured