feat(service): generic schema and search operations with an osl-tasks skill (#204)

* feat(service): add task and project operations with a Claude skill

- seven task operations shared by the CLI and the MCP server
- fixed status and priority vocabularies; references resolved by label
- OSW_PERSON_IRI plus three category overrides, all optional
- osl-tasks skill, installed by `osw skill install` or as a plugin
- reads the stored page uncached, and verifies a write really landed

* docs(service): correct the cause of the emptied reference lists

- oold's LinkedBaseModel.__init__ clears them, not _store
- no wiki call is involved; cls(**jsondata) alone is enough
- rename the test to match

* feat(service): derive SMW property names from the category @context

- read the field-to-property mapping from the category schema chain
- cache the merged context per WtSite, cleared by clear_cache
- keep the hardcoded names as a fallback when the schema is unreadable
- alias printouts to the property name; SMW keys them by display label
- raise instead of querying a property the @context does not declare

* feat(service): add generic schema, search and validation operations

- search ask: printouts parameter, result keys forced by an alias
- search label: find an entity or category by its display title
- schema get: resolve option merges the category inheritance chain
- schema props: expose the Semantic MediaWiki property map
- entity validate: check a payload against the resolved schema

* fix(service): reconcile validate_entity with the write path

- exempt uuid and type from required: the osw model supplies both
- report pages the schema walk could not use as `skipped`, with a reason
- treat a blank schema slot as absent, not as a parse failure
- drop a skipped entry when a shorter branch read that page successfully
- guard a malformed `required` so it still surfaces as SchemaError

* feat(service): add schema field-usage operation

- count per category field how many stored instances populate it
- answers which of several same-shaped fields real data uses
- guard the category against ask-query injection, as search does
- read instances uncached, like the schema walk in the same module
- report nothing when the sample is empty, and say why a page failed

* refactor(service): drop the task read and render operations

- list_tasks, list_projects and list_persons are covered by the generic
  search ask and search label operations
- render_task_view wrote a local Markdown file, which the skill does itself
- _resolve_ref now names search_by_label instead of the removed list ops
- OSW_PERSON_IRI is no longer read by any operation

* fix(service): report created, updated and skipped pages separately

- default overwrite changes from 'keep existing' to 'true', so an update writes
- created/updated split comes from the pre-write WtPage.exists flag
- 'keep existing' now reports the page as skipped instead of updated
- the ledger records only pages that were actually written

* docs(skill): drive osl-tasks from the generic operations

- replaces the task-specific commands with entity, schema and search ops
- keeps the three category page names in prose; they are not discoverable
- status and priority vocabularies are read from the category schema
- records the update-by-uuid rule and the required-label validation
- documents the printout value shapes returned by an ask query

* refactor(service): remove the task service module

- create_task, update_task and create_person are covered by the osl-tasks
  skill driving the generic entity, schema and search operations
- drops the 'task' CLI group and its three MCP tools
- keeps the four OSW_*_CATEGORY and OSW_PERSON_IRI variables; no operation
  reads them any more, the skill reads the environment directly
- corrects the documented status and prio vocabularies: they store page
  names read from the category schema, not the words the commands took

* fix(skill): validate before the first write, and cover the task settings

- the skill now runs 'entity validate' once per run, which catches a wrong
  status page name against the schema enum before anything is stored
- adds the alias mapping the deleted module held, as prose
- states that the four env variables are unreachable through the MCP server
- a config test now covers the four settings no operation reads

* docs(service): name the two terms that could desync the skipped check

* build(release): stamp the osw version into the osl-tasks skill

- SKILL.md carries it as metadata.version, the Agent Skills spec field
- python-semantic-release rewrites it with pyproject.toml and CITATION.cff
- a test fails when the two versions differ or the entry is removed

* test(release): check the version bump touches only the skill frontmatter

* build(release): stamp the osw version into the plugin manifest too

- register .claude-plugin/plugin.json:version with python-semantic-release
- set the plugin and skill versions to the current 2.7.0 after the rebase
- parametrize the three version guard tests over skill and plugin

* test(release): cover CITATION.cff in the version stamping guards

- add the third stamped file to both parametrized guard tests
- compare against the release tool's own read, not a UTF-8 read
- name all four stamped files in the release workflow comment

* test(release): drop the version equality check

- a PR is tested against its merge with main, so a release there leaves a
  branch that edits SKILL.md with an older version in that file only
- the check failed on this PR for that reason, not for a real defect
- registration and replacement tests still cover the rot that matters
- set the skill and plugin versions to main's current 2.7.1

Author: LukasGold

.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "osw-python",
+  "description": "Skills for working with OpenSemanticLab wikis through the osw CLI and MCP server.",
+  "owner": {
+    "name": "OpenSemanticLab",
+    "url": "https://github.com/OpenSemanticLab"
+  },
+  "plugins": [
+    {
+      "name": "osl-tasks",
+      "source": "./",
+      "description": "Task and project management for OpenSemanticLab, driven by the osw CLI and MCP server."
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "osl-tasks",
+  "displayName": "OSL task management",
+  "description": "Task and project management for OpenSemanticLab, driven by the osw CLI and MCP server.",
+  "version": "2.7.1",
+  "author": {
+    "name": "OpenSemanticLab"
+  },
+  "homepage": "https://github.com/OpenSemanticLab/osw-python",
+  "repository": "https://github.com/OpenSemanticLab/osw-python",
+  "license": "Apache-2.0",
+  "keywords": ["opensemanticlab", "osl", "tasks", "wiki", "semantic-mediawiki"],
+  "skills": ["./src/osw/skills/"]
+}

.github/workflows/on-release-main.yml

@@ -1,9 +1,10 @@
 # Automated release: python-semantic-release analyzes the conventional
 # commits on main, and when a release is due it bumps the static version in
-# pyproject.toml and CITATION.cff, updates CHANGELOG.md, relocks uv.lock,
-# commits, tags vX.Y.Z, pushes and creates the GitHub release. Publishing
-# happens in this same run: pushes made with GITHUB_TOKEN do not retrigger
-# workflows, so a tag-triggered publish would never fire.
+# pyproject.toml, CITATION.cff, the osl-tasks skill and the Claude Code
+# plugin manifest, updates CHANGELOG.md, relocks uv.lock, commits, tags
+# vX.Y.Z, pushes and creates the GitHub release. Publishing happens in this
+# same run: pushes made with GITHUB_TOKEN do not retrigger workflows, so a
+# tag-triggered publish would never fire.
 #
 # Filename and environment name are load-bearing: the PyPI trusted
 # publisher (OIDC) references workflow "on-release-main.yml" and

docs/tools/cli.md

@@ -32,11 +32,12 @@ Commands are grouped by subject:
 
 | Group | Commands |
 | --- | --- |
-| `entity` | `get`, `put`, `export`, `delete` |
+| `entity` | `get`, `put`, `export`, `delete`, `validate` |
 | `file` | `info`, `cat`, `write`, `download`, `upload` |
-| `search` | `ask`, `titles`, `content`, `entities`, `sparql` |
+| `search` | `ask`, `titles`, `content`, `entities`, `sparql`, `label` |
 | `slot` | `list`, `get`, `set` |
-| `schema` | `get` |
+| `schema` | `get`, `props`, `usage` |
+| `skill` | `install` |
 | `instances` | `list`, `status` |
 | `ledger` | `path` |
 | top level | `status` |
@@ -79,3 +80,36 @@ form.
 help.
 
 Failures exit non-zero with a short message on stderr and no traceback.
+
+## Tasks and projects
+
+There is no dedicated command group for tasks. Reading local todos into an
+OSL wiki as Task entities, and reading tasks, projects and persons back out,
+is done with the generic `entity`, `schema` and `search` commands against the
+three OSL core categories (Task, Person, Project).
+
+**Configuration.** Four environment variables affect this, and all are
+optional: `OSW_PERSON_IRI`, `OSW_TASK_CATEGORY`, `OSW_PERSON_CATEGORY` and
+`OSW_PROJECT_CATEGORY`. Reading always queries the shared OSL core category,
+since MediaWiki category membership includes the whole subclass tree, so a
+task kept in a local subclass is found without any configuration. The three
+category overrides only change where a newly created task, person or project
+is written.
+
+**Vocabularies.** `status` and `prio` store the page name of a wiki item, not
+a word. Read the allowed values from the category schema with `osw schema get
+<task category> --resolve`: `status` carries them in `enum`, and `prio` names
+the category that holds them in `range`. A stock instance offers To do, In
+work and Done for `status`, and High, Medium and Low for `prio`. A due date is
+written to `end_date_time`, since the Task category has no due-date property.
+
+### The Claude Code skill
+
+The skill that drives this ships at `src/osw/skills/osl-tasks/SKILL.md`.
+Install it one of two ways:
+
+1. `osw skill install`, which copies it to `~/.claude/skills/osl-tasks/`.
+2. `/plugin marketplace add OpenSemanticLab/osw-python` then
+   `/plugin install osl-tasks`.
+
+A new Claude Code session picks it up with no further action.

docs/tools/configuration.md

@@ -111,6 +111,10 @@ set wins:
 | `OSW_MAX_RESULTS` | `OSW_MCP_MAX_RESULTS` | Default result cap (100) |
 | `OSW_MAX_CHARS` | `OSW_MCP_MAX_CHARS` | Result size cap in characters (100000) |
 | `OSW_VERBOSE` | `OSW_MCP_VERBOSE` | `true` prints the configuration source report |
+| `OSW_PERSON_IRI` | | Page name of the operator's own Person entity, read by the osl-tasks skill to filter tasks by actionee |
+| `OSW_TASK_CATEGORY` | | Category a newly created task is written to, read by the osl-tasks skill |
+| `OSW_PERSON_CATEGORY` | | Category a newly created person is written to, read by the osl-tasks skill |
+| `OSW_PROJECT_CATEGORY` | | Category a newly created project is written to, read by the osl-tasks skill |
 
 ## Windows paths in a `.env` file
 

pyproject.toml

@@ -38,6 +38,9 @@ dependencies = [
     "PyLD",
     "SPARQLWrapper",
     "jsonpath-ng",
+    # validates jsondata against a resolved JSON Schema in
+    # osw.service.ops.entities.validate_entity
+    "jsonschema>=4.0",
     "numpy",
     "pyyaml",
     "typing_extensions",
@@ -303,7 +306,8 @@ preview = true
 
 [tool.semantic_release]
 # python-semantic-release owns the version: it reads the conventional commits
-# on main, bumps the static version below and in CITATION.cff, updates the
+# on main, bumps the static version below, in CITATION.cff, in the osl-tasks
+# skill's frontmatter and in the Claude Code plugin manifest, updates the
 # changelog, relocks uv.lock, commits, tags (vX.Y.Z) and creates the GitHub
 # release. Publishing to PyPI happens in the same workflow run
 # (on-release-main.yml).
@@ -315,7 +319,14 @@ commit_message = "chore(release): v{version} [skip ci]"
 allow_zero_version = true
 exclude_commit_patterns = ['''chore\(release\):.*''']
 version_toml = ["pyproject.toml:project.version"]
-version_variables = ["CITATION.cff:version"]
+version_variables = [
+    "CITATION.cff:version",
+    "src/osw/skills/osl-tasks/SKILL.md:version",
+    # Claude Code caches an installed plugin under its version string, so a
+    # version that never changes keeps plugin users on the skill they first
+    # installed.
+    ".claude-plugin/plugin.json:version",
+]
 # relock so uv.lock's own pin of osw's version stays consistent, and include
 # the relocked file in the release commit
 build_command = "uv lock"

src/osw/cli/main.py

@@ -323,6 +323,7 @@ def command(**kwargs: Any) -> None:
     "schema": "Category JSON Schemas.",
     "search": "Find pages. OSW pages are titled by OSW-ID, so use 'ask' "
     "to search by name.",
+    "skill": "Install the Claude Code skills that ship with this package.",
     "slot": "Read and write individual page slots.",
 }
 

src/osw/cli/ops.py

@@ -148,6 +148,45 @@ def ledger_path(ctx: Context) -> dict:
     return {"path": str(ctx.ledger.path)}
 
 
+@operation(
+    group="skill",
+    cli_name="install",
+    surfaces=frozenset({"cli"}),
+    idempotent_hint=True,
+)
+def install_skill(
+    ctx: Context,
+    name: str = "osl-tasks",
+    target_dir: Optional[str] = None,
+    force: bool = False,
+) -> dict:
+    """Install a Claude Code skill that ships with this package.
+
+    Copies the packaged skill directory ``src/osw/skills/<name>`` to
+    ``~/.claude/skills/<name>`` (or under ``target_dir`` when given). A new
+    Claude Code session picks the installed skill up automatically, with no
+    further action needed. This is the alternative to installing the
+    osw-python plugin from its marketplace.
+    """
+    src = Path(__file__).resolve().parent.parent / "skills" / name
+    if not src.is_dir():
+        available = sorted(p.name for p in src.parent.iterdir() if p.is_dir())
+        raise errors.NotFound(
+            f"No packaged skill named '{name}'. Available: {', '.join(available)}."
+        )
+
+    base = Path(target_dir) if target_dir else Path.home() / ".claude" / "skills"
+    dest = base / name
+    if dest.exists() and not force:
+        raise errors.OpError(f"'{dest}' already exists. Pass --force to overwrite it.")
+
+    shutil.copytree(src, dest, dirs_exist_ok=True)
+    files = sorted(
+        p.relative_to(dest).as_posix() for p in dest.rglob("*") if p.is_file()
+    )
+    return {"name": name, "source": str(src), "target": str(dest), "files": files}
+
+
 @operation(
     group="instances",
     cli_name="list",

src/osw/mcp/server.py

@@ -35,8 +35,11 @@
 Entity and page titles are full MediaWiki page names, e.g. "Item:OSW1234...",
 never a bare id or label.
 
-Before creating or updating an entity, fetch its category's JSON Schema
-(get_category_schema) so the written jsondata validates against it.
+Before creating or updating an entity, get its category's JSON Schema with
+get_category_schema(resolve=True) - the unresolved schema alone is usually
+missing inherited properties - then check the payload with validate_entity
+before writing it. A new entity does not need "uuid" or "type" in its
+payload, since create_or_update_entity generates both itself.
 
 This server has no filesystem access: file content moves inline as text, not
 as a path. For anything path-based (uploading/downloading a local file, the

src/osw/service/config.py

@@ -40,6 +40,10 @@
 ENV_MAX_CHARS = ("OSW_MAX_CHARS", "OSW_MCP_MAX_CHARS")
 ENV_FILE = ("OSW_ENV_FILE", "OSW_MCP_ENV_FILE")
 ENV_VERBOSE = ("OSW_VERBOSE", "OSW_MCP_VERBOSE")
+ENV_TASK_CATEGORY = ("OSW_TASK_CATEGORY",)
+ENV_PERSON_CATEGORY = ("OSW_PERSON_CATEGORY",)
+ENV_PROJECT_CATEGORY = ("OSW_PROJECT_CATEGORY",)
+ENV_PERSON_IRI = ("OSW_PERSON_IRI",)
 
 
 def _first_env(names: tuple[str, ...]) -> Optional[str]:
@@ -64,6 +68,10 @@ def _first_env(names: tuple[str, ...]) -> Optional[str]:
     "max_results": ENV_MAX_RESULTS,
     "max_chars": ENV_MAX_CHARS,
     "verbose": ENV_VERBOSE,
+    "task_category": ENV_TASK_CATEGORY,
+    "person_category": ENV_PERSON_CATEGORY,
+    "project_category": ENV_PROJECT_CATEGORY,
+    "person_iri": ENV_PERSON_IRI,
 }
 
 
@@ -105,6 +113,18 @@ class Settings(BaseModel):
     # Only controls the startup configuration report. No tool or command
     # reads it, and Settings.redacted() deliberately does not expose it.
     verbose: bool = False
+    # Category a newly created task, person or project is written to. No
+    # operation reads these three; the osl-tasks skill reads the env variables
+    # directly, and only when a new entity has to go into a local subclass
+    # instead of the shared OSL core category.
+    task_category: Optional[str] = None
+    person_category: Optional[str] = None
+    project_category: Optional[str] = None
+    # Full page name of the Person entity representing the operator, e.g.
+    # "Item:OSW...". No operation reads it; the osl-tasks skill reads the env
+    # variable directly to filter tasks by their actionee. An actionee is never
+    # assigned from it, so a task created without an explicit actionee has none.
+    person_iri: Optional[str] = None
 
     @field_validator("domain")
     @classmethod
@@ -166,6 +186,17 @@ def _validate_state_dir(cls, value: Optional[str]) -> Optional[str]:
             )
         return value
 
+    @field_validator(
+        "task_category", "person_category", "project_category", "person_iri"
+    )
+    @classmethod
+    def _validate_non_blank(cls, value: Optional[str]) -> Optional[str]:
+        if value is None:
+            return value
+        if not value.strip():
+            raise ValueError("must not be empty or whitespace-only")
+        return value
+
     @field_validator("cred_filepath")
     @classmethod
     def _validate_cred_filepath(cls, value: Optional[str]) -> Optional[str]:
@@ -755,6 +786,10 @@ def load(strict: bool = True) -> Settings:
         cred_filepath=cred_filepath,
         sparql_endpoint=_first_env(ENV_SPARQL_ENDPOINT),
         state_dir=_first_env(ENV_STATE_DIR),
+        task_category=_first_env(ENV_TASK_CATEGORY),
+        person_category=_first_env(ENV_PERSON_CATEGORY),
+        project_category=_first_env(ENV_PROJECT_CATEGORY),
+        person_iri=_first_env(ENV_PERSON_IRI),
     )
     # An unset or blank/whitespace-only variable falls back to the model
     # default; pass the raw string only when there is one to validate. Letting