skillstate-kit 0.1.1__tar.gz → 0.2.0__tar.gz

skillstate_kit-0.2.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.2.0 — portable task execution state
+
+- Add an optional evidence-backed task profile with ordered milestones, explicit revalidation, per-resource freshness checks and validated completion.
+- Add host discovery and a shared adapter contract; install project lifecycle instructions automatically without replacing unrelated AGENTS.md or CLAUDE.md content.
+- Add selective project host connection/removal and thin Codex/Claude plugin assets using the same Python runtime.
+- Add `run find`, `task start/checkpoint/complete` and four additive MCP tools. Preserve the original twelve MCP tools, public SDK imports, semantic skill bundles and SQLite v1 stores.
+- Add a real, paired Codex coding experiment with fresh sessions after stages 2/4/6, independent correctness checks, actual host-reported token usage and explicit measurement limitations.
+- Preserve the existing external smolagents acceptance. Claude Code live acceptance remains unexecuted; a reproducible manual procedure is provided.
+- Execution-state persistence does not control native host transcripts or guarantee token, latency or cost savings.
+
+## 0.1.2 — desktop connection and host acceptance
+
+- Explicit `connect claude-desktop` / `disconnect claude-desktop` commands, with Microsoft Store and standalone Windows detection, macOS defaults and explicit config paths.
+- Preserve unrelated app settings, isolate server names per project, serialize connection writes, refuse user-modified entries, and roll back configuration on receipt write failure.
+- Include desktop connections in `doctor`; retain state when disconnecting.
+- Disambiguate the source resource directory for root-level SKILL.md files.
+- Add a reproducible synthetic invoice acceptance exercise and report actual host successes and blockers separately.
+- Codex completed a real MCP review and handoff. Follow-up verification confirmed that Claude Desktop resumed the same run after the initial permission/timeout interruption, saved second-review evidence and completed at revision 4. Antigravity desktop reported tools unavailable; IDE login was not configured. These are not three passing end-to-end host tests.
+
+## 0.1.1 — public distribution
+
+- Self-contained PyPI package description with installation and SDK examples.
+- GitHub OIDC publishing workflow: full test matrix, clean installation, optional TestPyPI rehearsal, PyPI and downloaded package verification.
+- Verify registry file hashes against the tested artifacts before installation.
+- No changes to the runtime or storage contract from 0.1.0.
+
+## 0.1.0 — initial alpha
+
+- Source-preserving SKILL.md conversion and Python test tracking profile.
+- Source-bound semantic proposal preparation/validation and optional stateless JSON model adapter.
+- Immutable skill definitions and source drift detection.
+- SQLite revisions, ownership handoff, operation intents and explicit reconciliation.
+- Managed async runtime with bounded context and tool argument validation.
+- Project-scoped Codex, Claude Code and Antigravity skill/MCP installers.
+- STDIO MCP server, protocol smoke test, CLI and text artifact store.
+- Offline examples, cross-platform CI and package checks.
+
+Not included: native transcript replacement, arbitrary code rewriting, live certification of every host version, distributed multi-tenant storage, automatic external-effect rollback or reproduced paper benchmarks.

{skillstate_kit-0.1.1 → skillstate_kit-0.2.0}/CITATION.cff

@@ -2,7 +2,7 @@ cff-version: 1.2.0
 message: "Cite this repository and the SKILL.state paper that inspired its explicit-state execution pattern."
 title: "skillstate-kit"
 type: software
-version: 0.1.1
+version: 0.2.0
 license: MIT
 authors:
   - name: "Atakan Emre"

{skillstate_kit-0.1.1 → skillstate_kit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillstate-kit
-Version: 0.1.1
+Version: 0.2.0
 Summary: Compile existing agent skills into portable, validated execution state.
 Project-URL: Homepage, https://github.com/Atakan-Emre/skillstate-kit
 Project-URL: Repository, https://github.com/Atakan-Emre/skillstate-kit
@@ -39,26 +39,42 @@ Description-Content-Type: text/markdown
 
 # skillstate-kit
 
-**Portable, validated execution state for agent skills.**
+**A portable, validated execution-state layer for long-running AI agents.**
 
-Convert an existing `SKILL.md` into a state-backed skill, retain durable checkpoints, and integrate the same execution engine into a Python application.
+Maintain task progress, observations, artifacts and operation state outside conversational history. Use your existing coding agent through CLI/MCP and project integrations, or embed the same canonical engine in Python. Semantic generation from existing skills remains supported. No custom Python agent is required for host integration.
 
-Python 3.11+ · MIT license · Initial alpha
+Python 3.11+ · MIT license · Alpha
 
 ## Install
 
 ```bash
-python -m pip install "skillstate-kit[mcp,http]"
-skillstate demo
+python -m pip install "skillstate-kit[mcp]"
+skillstate init
+skillstate doctor --mcp
 ```
 
-The core package requires no model account. The demo uses an explicitly scripted model and local tools; it is not a benchmark of real-model performance.
+Run setup in your project. Host detection installs the applicable project lifecycle and generator skills; unrelated instructions/configuration are preserved. After reloading discovery, use your agent normally. The integration guides it to inspect compatible runs, preserve completed work, record evidence and validate completion.
+
+The base package also supports `pip install skillstate-kit` and `skillstate init` through CLI instructions. MCP is optional. The core requires no model account; your host supplies its model. `skillstate demo` is an explicitly scripted offline example.
 
 Optional extras:
 
 - `mcp`: a project-scoped STDIO MCP server and connection diagnostics.
 - `http`: a stateless adapter for a configured JSON-compatible chat-completions endpoint.
 
+## Task lifecycle
+
+The optional task profile provides `task_start`, `task_checkpoint` and `task_complete` over CLI/MCP. Milestones reference artifacts, completion time and resource fingerprints; repeated milestones require an explicit revalidation reason. Completion validates required steps, evidence integrity, blockers and freshness. Agent-reported evidence does not independently prove business truth. Existing semantic state schemas and run APIs remain supported.
+
+`skillstate hosts detect` lists discovery evidence. `skillstate init --host codex --mcp` or `--host claude-code --mcp` selects a project integration. `skillstate doctor codex` checks that integration. `skillstate disconnect codex` reverses its owned setup while retaining state.
+
+Execution-state optimization does not remove a host's native transcript. Token, latency and cost improvements must be measured independently; smaller application context is not proof of provider savings.
+
+A real paired Codex coding trial passed 29 independent checks in both modes and
+preserved the integrated run across four fresh sessions. It used more tokens and
+wall time with SkillState on that small task. See the
+[measurement report](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/benchmarks/coding-agent.md).
+
 ## Use an existing skill
 
 Run these commands in your target project. Replace `skills/qa/SKILL.md` with your existing skill file:
@@ -83,6 +99,19 @@ The preparation response contains source text, its fingerprint and the proposal
 
 You can also supply an explicitly configured endpoint with `--base-url` and `--model`. Terminal commands do not borrow your IDE's model credentials.
 
+## Claude Desktop Chat
+
+Version 0.1.2 adds an explicit local connection, separate from Claude Code:
+
+```console
+skillstate connect claude-desktop
+skillstate doctor --mcp
+```
+
+Fully quit and reopen Claude Desktop, use **Chat**, and approve the tool calls you intend to allow. The installer preserves unrelated settings and uses a separate server name per project. Windows standalone/Microsoft Store and macOS paths are supported; `--config PATH` selects a custom location. If two Windows configs exist, choose explicitly. Disconnect with `skillstate disconnect claude-desktop`; run data remains intact.
+
+Live acceptance evidence: Codex used eight real MCP calls to record a synthetic invoice review and hand it to Claude Desktop. After an initial permission/timeout interruption, Desktop resumed the same run, saved a second-review artifact and completed at revision 4. A separate process verified the stored state, both artifacts and the event history. This representative Codex-to-Claude Desktop Chat success does not establish universal desktop compatibility.
+
 ## Python integration
 
 This complete example uses a scripted model. Replace `model` and `record` with your own model and service functions:

skillstate_kit-0.2.0/README.md

@@ -0,0 +1,264 @@
+<p align="center">
+  <img src="docs/assets/logo.svg" alt="skillstate-kit — State that survives the next session." width="1040">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/skillstate-kit/"><img src="https://img.shields.io/pypi/v/skillstate-kit?color=246b52" alt="PyPI version"></a>
+  <img src="https://img.shields.io/badge/Python-3.11%2B-246b52" alt="Python 3.11 or newer">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-246b52" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/Status-Alpha-b76538" alt="Alpha release">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/skillstate-kit/">PyPI</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#python-integration">Python example</a> ·
+  <a href="docs/README_TR.md">Türkçe</a> ·
+  <a href="docs/host-acceptance.md">Verified integrations</a>
+</p>
+
+# skillstate-kit
+
+**A portable, validated execution-state layer for long-running AI agents.**
+
+Keep task progress, observations, artifacts and operation state outside conversational history. Use your existing agent through project skills, CLI or MCP, or embed the canonical runtime in Python. Task-specific semantic state remains supported; no custom Python agent is required for host integration.
+
+By reducing redundant work and providing bounded application state, skillstate-kit is designed to improve long-horizon execution efficiency. Provider-level token, latency and cost effects depend on the host and require separate measurement.
+
+**Available on [PyPI](https://pypi.org/project/skillstate-kit/), open source under the [MIT license](LICENSE).** The project is in alpha; this checkout documents the `0.2.0` release candidate. Install the package from PyPI or explore and contribute to this repository.
+
+**External-project validation:** the existing Hugging Face smolagents SQL agent
+produced the same five correct results on 1,000 synthetic receipts before and
+after integration. The managed run resumed in a new process after an injected
+interruption, without repeating completed queries.
+[Read the experiment and its scope](docs/smolagents-acceptance.md).
+
+**Coding-agent measurement:** four fresh Codex sessions completed the same persisted
+task and passed 29 independent checks. This small paired trial used **more**, not
+fewer, tokens and wall time with SkillState. [Read the measured results and
+limitations](docs/benchmarks/coding-agent.md) before making performance claims.
+
+## Why skillstate-kit?
+
+| Capability | What it gives you |
+|---|---|
+| Source-preserving generation | Keep your instructions and add structured progress tracking. |
+| Domain-specific state | Let your agent propose fields and steps, then validate the proposal against the source. |
+| Durable checkpoints | SQLite transactions, revision checks, evidence artifacts and explicit ownership handoff. |
+| Controlled operations | Validate decisions before execution and retain uncertain outcomes for reconciliation. |
+| Python, CLI and MCP | Use one state engine across application code and supported agent integrations. |
+
+## Quick start
+
+### 1. Install
+
+Use Python **3.11 or newer**, preferably in your project's virtual environment:
+
+```bash
+python -m pip install "skillstate-kit[mcp]"
+skillstate init
+skillstate doctor --mcp
+```
+
+Run setup inside your target project. `init` detects supported project hosts, installs lifecycle/generator skills and preserves unrelated instructions/configuration. Reload host discovery, then work normally—for example: **“Implement duration parsing for this project.”** The integration guides your agent to inspect existing runs, record evidence-backed milestones and validate completion.
+
+The base `pip install skillstate-kit` also works with `skillstate init` through CLI instructions. MCP is optional. `skillstate demo` remains an explicitly scripted offline example. See [host setup and distribution](docs/integrations.md) and [execution state versus chat history](docs/execution-state.md).
+
+For Python-only use, install `skillstate-kit`. Add the `http` extra when you need a configured JSON-compatible model endpoint: `python -m pip install "skillstate-kit[mcp,http]"`.
+
+### 2. Convert your existing skill
+
+Run these commands **inside the project you want to integrate**. Replace `skills/qa/SKILL.md` with your existing skill file:
+
+```bash
+skillstate init --host codex --mcp
+skillstate generate skills/qa/SKILL.md --name qa-state --install
+skillstate validate qa-state
+skillstate doctor --mcp
+```
+
+`init` sets up the selected host; `generate --install` writes the generated skill wrappers for the three project adapters. Original source files remain unchanged. To target another directory, place `--project PATH` before the subcommand.
+
+**No existing skill file?** In a Python project, start with the built-in test workflow:
+
+```bash
+skillstate generate . --profile python-tests --name tests-state --install
+skillstate validate tests-state
+```
+
+This produces test-oriented tracking instructions from a bounded project inventory. It does not infer every business rule in your application.
+
+### 3. Ask your agent to use it
+
+After your host discovers the installed skills and MCP server, ask:
+
+> Use qa-state for this task. Open a run, record progress and evidence, and leave a checkpoint if the work is interrupted.
+
+For agent-assisted **domain-specific generation**, use the installed `generate-skill-state` skill:
+
+> Generate skill state from skills/qa/SKILL.md. Propose the fields and steps this procedure needs, validate the proposal, and install the result.
+
+Direct CLI generation creates generic tracking state. Agent-assisted generation can propose domain-specific state. **Generating a definition does not execute the task.** The host still runs the procedure and records its progress.
+
+## Choose your environment
+
+Use `skillstate hosts detect` to inspect discovery evidence and `skillstate doctor codex` or `skillstate doctor claude-code` for focused checks. Detection is not a live execution test. Project instruction blocks encourage automatic lifecycle use; host/model selection and permissions still apply.
+
+| Environment | Setup inside your project | Verified scope |
+|---|---|---|
+| Codex | `skillstate init --host codex --mcp` | Real MCP generation and continuation across two model sessions passed. |
+| Claude Desktop **Chat** | `skillstate connect claude-desktop` | Codex → Claude Desktop handoff and independent invoice review passed. |
+| Claude Code | `skillstate init --host claude-code --mcp` | Adapter available; a live Claude Code run has not been verified. |
+| Antigravity | `skillstate init --host antigravity --mcp` | Project skill and MCP configuration adapter available. |
+
+For Claude Desktop, **fully quit and reopen the app after connecting**, use Chat, and approve the requested tools in the app. This connection is separate from Claude Code and Cowork. Run `skillstate disconnect claude-desktop` to remove the connection while retaining run data.
+
+MCP configurations contain this machine's Python and project paths. Keep them local and repeat setup when changing machines or virtual environments. `doctor --mcp` checks the local server; it does not prove that a host's model can call it.
+
+See the [installation guide](docs/compatibility.md), [actual acceptance evidence](docs/host-acceptance.md), and [repeatable two-reviewer exercise](examples/desktop_acceptance/README.md).
+
+## Evidence-backed task lifecycle
+
+For a normal multi-step task, the agent can use `task_start`, `task_checkpoint` and `task_complete`. Identical goal/plan startup reuses its deterministic run ID; an intentionally new task can supply a new ID. A checkpoint references real artifacts and relevant resource fingerprints. Repeating a completed milestone requires a stated revalidation reason. Completion checks evidence integrity, remaining work, blockers and freshness—not the truth of arbitrary business claims.
+
+Existing semantic skills retain `run_open`/`run_update` and their own domain schema. All paths share one SQLite store and the existing pending/unknown operation protocol. See the [CLI reference](docs/cli.md).
+
+## Inspect a checkpoint
+
+Open a run for a generated definition, then inspect its state and audit trail:
+
+```bash
+skillstate run open qa-state --owner codex --id qa-001
+skillstate run context qa-001
+skillstate run events qa-001
+skillstate status
+```
+
+These commands create and inspect a run; they do not execute its steps. Use a new run ID for each task. To continue an existing task, read its context and resume that run rather than opening it again. Ownership changes use an explicit handoff with the current revision; see the [CLI lifecycle guide](docs/cli.md).
+
+## Python integration
+
+Save the following as `example.py`, then run `python example.py`. This complete example uses a **scripted model and a simulated tool**, so it works without credentials:
+
+```python
+import asyncio
+
+from skillstate import Skill, SkillRuntime, SQLiteStore, Tool, ToolResult
+
+async def main():
+    skill = Skill(
+        "record-job",
+        "Record the job; finish after its result is confirmed.",
+        {
+            "type": "object",
+            "properties": {"recorded": {"type": "boolean"}},
+            "required": ["recorded"],
+            "additionalProperties": False,
+        },
+        {"recorded": False},
+    )
+
+    def model(context):
+        if context["state"]["recorded"]:
+            return {"patch": [], "action": None, "done": True}
+        return {
+            "patch": [{"op": "set", "path": "/recorded", "value": True}],
+            "action": {"name": "record", "arguments": {}},
+            "done": False,
+        }
+
+    def record(arguments, operation_id):
+        return ToolResult(True, {"recorded": True, "operation_id": operation_id})
+
+    tool = Tool("record", "Record a job", {"type": "object", "additionalProperties": False}, record)
+    with SQLiteStore() as store:
+        store.create("example", skill, "worker", {"job": "example"})
+        runtime = SkillRuntime(store, model, [tool], completion_check=lambda s: s["recorded"])
+        result = await runtime.run("example", "worker")
+        print(result["status"], result["state"])
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Expected output:
+
+```text
+completed {'recorded': True}
+```
+
+Replace `model(context)` with your synchronous or asynchronous model callback, and `record` with a real tool that checks its result. Forward `operation_id` to the external service's idempotency facility when supported.
+
+The example uses an in-memory store for easy reruns. Use `SQLiteStore("jobs.sqlite3")` for durable storage. Create each run once; resume by reopening that database and calling `runtime.run` with the existing run ID and owner. See the [runnable source](examples/managed_runtime.py) and [runtime contract](docs/architecture.md).
+
+### Model decision contract
+
+```json
+{
+  "patch": [{"op": "set", "path": "/recorded", "value": true}],
+  "action": {"name": "record", "arguments": {}},
+  "done": false
+}
+```
+
+Finish with `{"patch": [], "action": null, "done": true}`. State updates use explicit `set`/`delete` operations and JSON Pointer paths. Setting `null` does not delete a key. No reasoning-trace field is accepted.
+
+## How it fits together
+
+```mermaid
+flowchart LR
+    Source[Existing skill or Python project] --> Generate[Tracking state or semantic proposal]
+    Generate --> Validate[Schema and source validation]
+    Validate --> Bundle[Versioned skill bundle]
+    Bundle --> Host[Agent via CLI or MCP]
+    Bundle --> Runtime[Python managed runtime]
+    Host <--> Store[(State, evidence and operation journal)]
+    Runtime <--> Store
+```
+
+| Execution mode | What skillstate-kit controls |
+|---|---|
+| Native agent integration | Validated state, checkpoints, explicit operation records and bounded returned context. The host owns its model and tools. |
+| Python managed runtime | Model context, decision validation, registered tool execution, retries and recorded outcomes. |
+
+Native integrations do not replace a host's conversation history or intercept every native tool. For the paper's history-free model-input pattern, use the managed runtime with a stateless model adapter. A terminal process cannot borrow your IDE's model subscription automatically.
+
+Definitions live in `.skillstate/definitions/`; private run data and artifacts live in `.skillstate/local/`. Source changes are detected before new runs. Existing runs retain their pinned definition and expose source drift.
+
+## Failure behavior
+
+| Event | Behavior |
+|---|---|
+| Invalid JSON, state or tool arguments | Reject before tool execution |
+| Stale revision or wrong owner | Reject; require a fresh read/handoff |
+| Tool reports failure | Keep prior state and record its observation |
+| Timeout, exception or invalid tool result | Mark `unknown`; require reconciliation |
+| Process exits after reserving an operation | Retain the pending intent; do not replay automatically |
+| Event write fails during result commit | Roll back state, operation outcome and event together |
+| User edits installed files/configuration | Preserve changes and report a conflict |
+
+SQLite does not create a distributed transaction with external APIs. A checkpoint cannot undo an external side effect. Owner IDs coordinate local clients; they are not an authentication boundary. Read [the execution contract](docs/architecture.md) before using mutating tools.
+
+## Development
+
+```bash
+python -m pip install uv
+uv sync --locked --extra dev
+uv run ruff check src tests examples
+uv run ruff format --check src tests examples
+uv run pytest --cov=skillstate --cov-fail-under=85
+uv run python -m build
+uv run twine check dist/*
+```
+
+CI tests the Python/OS matrix, builds distributions and checks wheel installation. Tests include real MCP sessions, competing connections, crash recovery, configuration preservation, invalid schemas and source drift. Coverage is a regression signal, not proof of correctness.
+
+## Research and attribution
+
+An **independent implementation** inspired by [SKILL.state: Scalable Long-Horizon Agent Skills](https://arxiv.org/abs/2608.26263), by Sanket Badhe, Priyanka Tiwari and Jonghyun Chung. Not affiliated with or endorsed by the authors or their institutions.
+
+The managed runtime follows the explicit-state input pattern. Our compiler, host adapters, explicit patch format and operation journal are engineering extensions. No paper benchmark scores are claimed. [skill-state-minimal](https://github.com/kissishka/skill-state-minimal) was inspected as a comparison; its source is not bundled here.
+
+## License and contributing
+
+[MIT](LICENSE). See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), [CHANGELOG.md](CHANGELOG.md) and [release guidance](docs/releasing.md).

{skillstate_kit-0.1.1 → skillstate_kit-0.2.0}/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Reporting
 
-Use GitHub private vulnerability reporting when available. While the repo is private, contact the maintainer through an existing private channel. Do not put credentials or exploitable production details in an issue or test another person's services.
+Use [GitHub private vulnerability reporting](https://github.com/Atakan-Emre/skillstate-kit/security/advisories/new) for security issues. Do not put credentials or exploitable production details in a public issue or test another person's services.
 
 ## Scope
 

{skillstate_kit-0.1.1 → skillstate_kit-0.2.0}/docs/PYPI_README.md

@@ -1,25 +1,41 @@
 # skillstate-kit
 
-**Portable, validated execution state for agent skills.**
+**A portable, validated execution-state layer for long-running AI agents.**
 
-Convert an existing `SKILL.md` into a state-backed skill, retain durable checkpoints, and integrate the same execution engine into a Python application.
+Maintain task progress, observations, artifacts and operation state outside conversational history. Use your existing coding agent through CLI/MCP and project integrations, or embed the same canonical engine in Python. Semantic generation from existing skills remains supported. No custom Python agent is required for host integration.
 
-Python 3.11+ · MIT license · Initial alpha
+Python 3.11+ · MIT license · Alpha
 
 ## Install
 
 ```bash
-python -m pip install "skillstate-kit[mcp,http]"
-skillstate demo
+python -m pip install "skillstate-kit[mcp]"
+skillstate init
+skillstate doctor --mcp
 ```
 
-The core package requires no model account. The demo uses an explicitly scripted model and local tools; it is not a benchmark of real-model performance.
+Run setup in your project. Host detection installs the applicable project lifecycle and generator skills; unrelated instructions/configuration are preserved. After reloading discovery, use your agent normally. The integration guides it to inspect compatible runs, preserve completed work, record evidence and validate completion.
+
+The base package also supports `pip install skillstate-kit` and `skillstate init` through CLI instructions. MCP is optional. The core requires no model account; your host supplies its model. `skillstate demo` is an explicitly scripted offline example.
 
 Optional extras:
 
 - `mcp`: a project-scoped STDIO MCP server and connection diagnostics.
 - `http`: a stateless adapter for a configured JSON-compatible chat-completions endpoint.
 
+## Task lifecycle
+
+The optional task profile provides `task_start`, `task_checkpoint` and `task_complete` over CLI/MCP. Milestones reference artifacts, completion time and resource fingerprints; repeated milestones require an explicit revalidation reason. Completion validates required steps, evidence integrity, blockers and freshness. Agent-reported evidence does not independently prove business truth. Existing semantic state schemas and run APIs remain supported.
+
+`skillstate hosts detect` lists discovery evidence. `skillstate init --host codex --mcp` or `--host claude-code --mcp` selects a project integration. `skillstate doctor codex` checks that integration. `skillstate disconnect codex` reverses its owned setup while retaining state.
+
+Execution-state optimization does not remove a host's native transcript. Token, latency and cost improvements must be measured independently; smaller application context is not proof of provider savings.
+
+A real paired Codex coding trial passed 29 independent checks in both modes and
+preserved the integrated run across four fresh sessions. It used more tokens and
+wall time with SkillState on that small task. See the
+[measurement report](https://github.com/Atakan-Emre/skillstate-kit/blob/main/docs/benchmarks/coding-agent.md).
+
 ## Use an existing skill
 
 Run these commands in your target project. Replace `skills/qa/SKILL.md` with your existing skill file:
@@ -44,6 +60,19 @@ The preparation response contains source text, its fingerprint and the proposal
 
 You can also supply an explicitly configured endpoint with `--base-url` and `--model`. Terminal commands do not borrow your IDE's model credentials.
 
+## Claude Desktop Chat
+
+Version 0.1.2 adds an explicit local connection, separate from Claude Code:
+
+```console
+skillstate connect claude-desktop
+skillstate doctor --mcp
+```
+
+Fully quit and reopen Claude Desktop, use **Chat**, and approve the tool calls you intend to allow. The installer preserves unrelated settings and uses a separate server name per project. Windows standalone/Microsoft Store and macOS paths are supported; `--config PATH` selects a custom location. If two Windows configs exist, choose explicitly. Disconnect with `skillstate disconnect claude-desktop`; run data remains intact.
+
+Live acceptance evidence: Codex used eight real MCP calls to record a synthetic invoice review and hand it to Claude Desktop. After an initial permission/timeout interruption, Desktop resumed the same run, saved a second-review artifact and completed at revision 4. A separate process verified the stored state, both artifacts and the event history. This representative Codex-to-Claude Desktop Chat success does not establish universal desktop compatibility.
+
 ## Python integration
 
 This complete example uses a scripted model. Replace `model` and `record` with your own model and service functions:

skillstate_kit-0.2.0/docs/README_TR.md

@@ -0,0 +1,67 @@
+![skillstate-kit — Oturumlar arasında kalıcı görev durumu](assets/logo.svg)
+
+# Türkçe başlangıç
+
+[PyPI paketi](https://pypi.org/project/skillstate-kit/) · [Çalışan Python örneği](../README.md#python-integration) · [Kabul testleri](host-acceptance.md)
+
+skillstate-kit, AI agent'lar için taşınabilir bir görev yürütme durumu katmanıdır. İlerleme, kanıtlar ve işlem durumu konuşma geçmişinden ayrı saklanır. Python, CLI ve MCP aynı çekirdeği kullanır; özel bir Python agent yazmanız gerekmez. MIT lisansıyla açık kaynak olarak yayımlanır. Sürüm alpha durumundadır.
+
+**Dış proje doğrulaması:** Hugging Face smolagents'ın mevcut SQL agent'ı, 1.000 sentetik kayıt üzerindeki beş kontrolde entegrasyon öncesi ve sonrası aynı doğru sonuçları üretti. Skillstate ile çalışan süreç zorla kapatıldıktan sonra yeni süreç kalan iki sorguyla tamamlandı; bitmiş sorgular tekrarlanmadı. [Deneyin kapsamı, sonuçları ve tekrar çalıştırma adımları](smolagents-acceptance.md).
+
+## Kurulum
+
+Python 3.11 veya üzeri bir ortamda:
+
+```text
+python -m pip install "skillstate-kit[mcp]"
+```
+
+Ardından kullanacağınız projenin klasöründe:
+
+```text
+skillstate init
+skillstate doctor --mcp
+```
+
+0.2.0 ile `init`, algılanan proje ortamlarını seçer ve MCP kuruluysa yapılandırır. `skillstate hosts detect` seçim gerekçelerini gösterir. Yalnızca `pip install skillstate-kit` de yeterlidir: temel paket CLI üzerinden çalışır. Belirli bir ortam için `skillstate init --host codex --mcp` kullanabilirsiniz. MCP ayarları bu makineye ait Python/proje yollarını içerir.
+
+Agent oturumunu yeniledikten sonra normal görevinizi verin: “Bu projeye JWT doğrulaması ekle ve testlerini çalıştır.” Kurulan yönergeler agent'ı mevcut görevi bulmaya, uygun kaydı sürdürmeye ve kanıtlı adımlar kaydetmeye yönlendirir. Host'un yönergeleri izlemesi gerekir; paket her araç çağrısını zorla denetlemez.
+
+`skillstate run find` ile kayıtları, `skillstate run context RUN_ID` ile güncel durumu görebilirsiniz. Tamamlanan adımı yeniden kaydetmek açık bir yeniden doğrulama gerekçesi ister. Kaynak dosyası değişirse yalnızca o dosyaya bağlı kanıtlar eski olarak işaretlenir. [Durum ve doğrulama sözleşmesi](execution-state.md).
+
+**Ölçüm:** Yeni [kodlama deneyi](benchmarks/coding-agent.md) gerçek token ve süreyi ayrı raporlar. Kalıcı durumun çalışması otomatik maliyet tasarrufu anlamına gelmez; host'un konuşma geçmişini bu paket silemez.
+
+## Otomatik üretim
+
+Claude Desktop'ın **Chat** bölümünü kullanıyorsanız ayrıca `skillstate connect claude-desktop` çalıştırıp uygulamadan tamamen çıkın ve yeniden açın. Bu bağlantı Claude Code kurulumundan ayrıdır. Araç izinlerini uygulama içinde siz verirsiniz. `skillstate disconnect claude-desktop` bağlantıyı kaldırır, görev durumunu korur. Windows Store sürümü de desteklenir; birden fazla ayar dosyası bulunursa `--config DOSYA` ile seçilir.
+
+Gerçek uygulama testlerinin sonucu [kabul raporunda](host-acceptance.md), tekrar edilebilir örnek ise [örnek projede](../examples/desktop_acceptance/README.md). Codex'te gerçek MCP üretimi ve ayrı oturumdan devam etme; ayrıca Codex → Claude Desktop Chat devri ve ikinci incelemeyle tamamlama doğrulandı. Claude Code için canlı uygulama testi yapılmadı.
+
+Kurulumdan sonra agent'a “Generate skill state; bu skill'i durum yapısına dönüştür” diyebilirsiniz. Üretici kaynak envanterini hazırlayıp agent'ın önerdiği şemayı doğrular.
+
+Doğrudan `generate`, yönergeleri koruyan sınırlı bir genel ilerleme şeması oluşturur. Alana özel dönüşüm için agent destekli `--prepare`/`--proposal` akışı veya yapılandırılmış `--base-url`/`--model` kullanılır. Terminal, IDE model hesabını otomatik kullanmaz.
+
+## Çalıştırma ve devam
+
+Üretim komutu görevi çalıştırmaz. Agent'a “qa-state skill'ini bu görevde kullan, ilerlemeyi ve kanıtları kaydet” diyerek çalışmayı başlatın. Durumu terminalden incelemek için:
+
+```text
+skillstate run open qa-state --owner codex --id qa-001
+skillstate run context qa-001
+skillstate run events qa-001
+skillstate status
+```
+
+Her yeni görev için farklı bir run ID kullanın. Var olan göreve devam ederken yeniden açmak yerine mevcut durumu okuyun. Python ile doğrudan kullanım için [kopyalanıp çalıştırılabilen örneğe](../README.md#python-integration) bakın.
+
+Üretilen skill, state açma, okuma, güncelleme, işlem sonucu kaydetme ve ortamlar arasında devretme adımlarını içerir. Python projeleri `SkillRuntime` ile bütün model/araç döngüsünü yönetebilir.
+
+Native skill host'un konuşma geçmişini silmez. Makaledeki geçmiş taşımayan model girdisini kurmak için stateless adapter ile managed runtime kullanın.
+
+`pending` veya `unknown` bir dış işlemin sonucunun belirsiz olduğunu gösterir. Tekrarlamadan önce dış sistemden sonucu kontrol edin ve açıkça uzlaştırın. Checkpoint dış dünyadaki işlemi geri almaz.
+
+## Doğrulama
+
+`skillstate demo` model hesabı gerektirmeyen kontrollü örnektir. `doctor --mcp` gerçek yerel MCP bağlantısı kurar. Bunlar bütün IDE sürümlerinin davranışını veya makalenin performans sonuçlarını doğrulamaz.
+
+Ayrıntılar: [CLI](cli.md), [mimari](architecture.md), [ortam desteği](compatibility.md), [test matrisi](validation.md).

skillstate_kit-0.2.0/docs/architecture-audit.md

@@ -0,0 +1,40 @@
+# Architecture audit and implementation contract — 2026-09-07
+
+The pre-change architecture is intentionally retained: models/schema/jsonio → store/runtime → ProjectService → CLI/MCP → hosts/desktop. Flat modules already enforce useful boundaries; moving them into packages would break imports without product benefit.
+
+| Requested capability | Initial classification | Decision |
+|---|---|---|
+| Python SDK, transactional SQLite, revisions, ownership | ALREADY EXISTS | Preserve public contracts and database v1 |
+| Pending/unknown operation reconciliation | ALREADY EXISTS | Keep existing reservation protocol |
+| Semantic generation and immutable bundles | ALREADY EXISTS | Do not force task schemas onto old bundles |
+| Artifact integrity and bounded runtime context | ALREADY EXISTS | Reuse, keep audit outside model context |
+| Project installers, MCP, host-specific wrappers | PARTIAL | Add lifecycle discovery and isolated adapter registry |
+| Host detection and minimal init | MISSING | Detect without reading credentials; retain explicit host flags |
+| Evidence-backed task milestones and granular freshness | MISSING | Optional task profile via shared service, existing store |
+| Natural task startup and compatible-run discovery | PARTIAL | Lifecycle skill + managed instruction block; no guessing task identity |
+| Codex/Claude skill/plugin distribution | PARTIAL | Thin assets depending on Python CLI/MCP |
+| Source drift | PARTIAL | Existing bundle drift plus milestone resource fingerprints |
+| Cross-host handoff | ALREADY EXISTS | Extend acceptance, never reset state |
+| smolagents correctness/restart acceptance | ALREADY EXISTS | Preserve as a correctness experiment |
+| Coding-agent benchmark and real host measurements | MISSING | Deterministic feature fixture, baseline/integrated + boundaries 2/4/6 |
+| Claude Code live acceptance | MISSING | Execute if available, otherwise reproducible manual procedure |
+| Native transcript compression or universal token savings | SHOULD NOT IMPLEMENT | State explicit host limitations |
+| Command-string deduplication, second state engine, scheduler | SHOULD NOT IMPLEMENT | Use state/evidence/operation semantics |
+
+## Changes and compatibility
+
+Evolve hosts.py, service.py, cli.py and mcp_server.py; introduce small lifecycle and host-registry modules; add thin plugin assets and benchmark fixtures. Preserve store tables, Skill/Tool/SkillRuntime imports, existing CLI operations, all existing MCP tools, historical bundles and acceptance evidence. New lifecycle APIs are opt-in and cannot retroactively add completion requirements to arbitrary schemas.
+
+Risks: preserving edited AGENTS.md/CLAUDE.md sections; shared Codex/Antigravity skill paths; misleading host detection; stale evidence; interpreting repeated calls as unnecessary; assuming usage statistics equal billed cost. Address these with marked-block ownership, conflict-aware rollback, explicit detection evidence, per-resource hashes, reported repetition categories, and unavailable metrics rather than guessed numbers.
+
+## Phases and acceptance
+
+0. Audit and regression baseline: 113 passed / 1 Windows symlink privilege skip; 86.84% coverage.
+1. Registry/detection and reversible installation; explicit host flags remain supported.
+2. Codex lifecycle instructions and bounded compatible-run summaries.
+3. Claude Code lifecycle and thin plugin distribution, same Python engine.
+4. Evidence-backed milestones, explicit completion and cross-host continuation.
+5. Real coding fixture and baseline/integrated measurements. Session boundaries after stages 2/4/6. Independent correctness, repeated calls, search/read counts, context bytes, available host usage, wall time; cost only from explicitly configured pricing.
+6. Documentation, package smoke checks and full tests with >=85% coverage.
+
+Acceptance: old APIs/stores remain readable; no blind operation replay; instructions/config preserve unrelated edits; completed work requires evidence and justified revalidation; one canonical run survives fresh sessions/handoff; MCP and CLI use the same service; smolagents evidence stays valid; unexecuted host paths are never marked passing. Benchmark reports separate observed, measured, inferred and unavailable values.

{skillstate_kit-0.1.1 → skillstate_kit-0.2.0}/docs/architecture.md

@@ -61,3 +61,21 @@ Installers preflight conflicts, atomically replace individual files and preserve
 ## Deliberate limits
 
 No automatic native transcript replacement, full tool interception, arbitrary code rewriting, multi-machine run transfer, lease expiration, automatic compensation or exactly-once external effect guarantee. A sync handler can continue after an async timeout; callbacks are not sandboxed. These limits are part of the contract, not features implied by the paper.
+
+## Host registry and optional task lifecycle (0.2)
+
+`host_registry` implements a small HostAdapter protocol over the existing hosts
+and desktop installers. It provides detect/install/uninstall/doctor/manifest
+operations. No host name enters the SQLite schema or managed runtime. Core state,
+operations, evidence and bounded model inputs retain their existing boundaries.
+
+`lifecycle` defines an optional task profile and evidence/freshness validation.
+`ProjectService` exposes start_task, checkpoint_task, complete_task and find_runs
+in addition to the existing semantic run operations. CLI and the four additive
+MCP tools call this same service. SQLite remains schema v1; old imports and all
+twelve original MCP tools are preserved.
+
+Milestone records live in the run's validated state, not a second database.
+Artifact bodies and the event audit remain separate from working context. The
+profile is not forced onto domain-specific schemas. See [state semantics](execution-state.md)
+and [host installation](integrations.md) for boundaries and downgrade guidance.