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

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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. Claude Desktop discovered the server, displayed a tool permission request, then the call timed out without a result. 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.

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/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.1.2
 license: MIT
 authors:
   - name: "Atakan Emre"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillstate-kit
-Version: 0.1.1
+Version: 0.1.2
 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
@@ -83,6 +83,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. Desktop discovered the server and requested tool permission, but the call later timed out without a result; the second review was not completed. An independent MCP transport check subsequently passed. The tested Antigravity desktop session reported MCP tools unavailable, and its separate IDE required login. Generated configuration and transport tests do not establish successful execution in those hosts. No claim of universal desktop compatibility is made.
+
 ## Python integration
 
 This complete example uses a scripted model. Replace `model` and `record` with your own model and service functions:

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/README.md

@@ -5,10 +5,13 @@
 Turn an existing `SKILL.md` into a state-backed skill, use it from Codex, Claude Code or Antigravity, and resume work from a durable checkpoint. Embed the same runtime in Python when you need to control every model input and tool operation.
 
 [![CI](https://github.com/Atakan-Emre/skillstate-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/Atakan-Emre/skillstate-kit/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/skillstate-kit)](https://pypi.org/project/skillstate-kit/)
 ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
 ![License](https://img.shields.io/badge/license-MIT-green)
 
-**Release status:** `0.1.1` is an initial alpha. The development repository is private; public package installation uses PyPI. Tested local adapters are not live certification of every host application.
+**Release status:** `0.1.2` is an alpha. The development repository is private; public package installation uses PyPI. See the actual [host acceptance results](docs/host-acceptance.md) before relying on a specific desktop environment.
+
+[Published package](https://pypi.org/project/skillstate-kit/) · [Distribution verification](docs/releases/0.1.1.md)
 
 [Türkçe başlangıç](docs/README_TR.md) · [CLI](docs/cli.md) · [Architecture](docs/architecture.md) · [Compatibility](docs/compatibility.md) · [Validation](docs/validation.md)
 
@@ -19,6 +22,7 @@ Turn an existing `SKILL.md` into a state-backed skill, use it from Codex, Claude
 - **Durable state.** SQLite transactions, revision checks, ownership handoff and a persistent operation journal.
 - **Controlled execution.** Validate state and tool arguments, retain observations during retries, and stop ambiguous operations from being replayed automatically.
 - **Three host adapters.** Project-scoped skills and optional STDIO MCP configuration for Codex, Claude Code and Antigravity.
+- **Claude Desktop Chat connection.** Explicit, reversible app configuration with a separate server per project; normal tool approvals still apply.
 - **A Python SDK.** Bring your own model and tool functions. The core package requires no API key.
 
 ## Quick start
@@ -40,6 +44,8 @@ skillstate doctor --mcp
 
 After installing the package, run `init` and `generate` in your target project. `--project PATH` can also be placed **before** a subcommand. Generated MCP configurations use this machine's Python/project paths; keep them local. See [installation and compatibility](docs/compatibility.md).
 
+For Claude Desktop **Chat**, also run `skillstate connect claude-desktop`, then fully quit and reopen the app. Claude Code, Cowork and Desktop Chat have different integration surfaces. Try the [two-reviewer acceptance exercise](examples/desktop_acceptance/README.md) before using production data.
+
 After the host discovers `generate-skill-state`, ask:
 
 > Generate skill state from my existing QA skill and install it in this project.

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

@@ -44,6 +44,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. Desktop discovered the server and requested tool permission, but the call later timed out without a result; the second review was not completed. An independent MCP transport check subsequently passed. The tested Antigravity desktop session reported MCP tools unavailable, and its separate IDE required login. Generated configuration and transport tests do not establish successful execution in those hosts. No claim of universal desktop compatibility is made.
+
 ## Python integration
 
 This complete example uses a scripted model. Replace `model` and `record` with your own model and service functions:

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/docs/README_TR.md

@@ -24,6 +24,10 @@ skillstate doctor --mcp
 
 ## 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'in gerçek MCP devri doğrulandı; diğer uygulamalardaki eksik onay ve bağlantı adımları başarılı sayı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.

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/docs/cli.md

@@ -11,7 +11,24 @@ skillstate validate qa-state
 skillstate doctor --mcp
 ```
 
-Omit `--mcp` for CLI-only host usage. Omit host flags to install all three adapters. Installation is project-local; global installation and hooks are not included in 0.1.0.
+Omit `--mcp` for CLI-only host usage. Omit host flags to install all three project adapters. `init` remains project-local; no hooks are installed.
+
+### Claude Desktop Chat connection
+
+```text
+skillstate connect claude-desktop
+skillstate doctor --mcp
+skillstate disconnect claude-desktop
+```
+
+`connect` explicitly merges an app-wide MCP entry for this project. It requires
+the `mcp` extra and reports the config path and server name. Fully quit/reopen
+Claude Desktop and use Chat; allow only the tool calls you intend to authorize.
+Pass `--config PATH` when auto-detection is ambiguous or your platform uses a
+custom location. `disconnect` uses the saved receipt and retains all run data.
+It refuses to remove user-modified entries. `uninstall` does not perform this
+separate desktop disconnection. See [compatibility](compatibility.md) for the
+tested platform/surface limitations.
 
 `generate` defaults to bounded tracking state while preserving the source instructions. For a Python project, `--profile python-tests` supplies test-oriented tracking instructions. It scans AST without importing project modules. Multiple source SKILL.md files require selecting one; it does not silently combine unrelated skills.
 

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/docs/compatibility.md

@@ -7,6 +7,7 @@
 | Codex | `.agents/skills/<name>/SKILL.md` | `.codex/config.toml` | Native CLI skill + STDIO MCP |
 | Claude Code | `.claude/skills/<name>/SKILL.md` | `.mcp.json` | Native CLI skill + STDIO MCP |
 | Antigravity | `.agents/skills/<name>/SKILL.md` | `.agents/mcp_config.json` | Native CLI skill + STDIO MCP |
+| Claude Desktop Chat | MCP generation tools | App-wide `claude_desktop_config.json`, one project per entry | Explicit `connect` command; tool approvals required |
 
 The shared `.agents/skills` output is installed once for Codex/Antigravity. State is canonical in one project-local database, not copied into each host folder. These adapters target documented local discovery/configuration paths, not cloud or remote sessions.
 
@@ -22,6 +23,18 @@ If discovery does not refresh, reload/restart the host as its documentation requ
 
 ## Verification levels
 
+### Claude Desktop Chat (0.1.2)
+
+Use `skillstate connect claude-desktop` in the target project, then fully quit/reopen Claude Desktop. The command auto-detects the standalone or Microsoft Store Windows config and the standard macOS path. Use `--config PATH` for other locations or ambiguous installs. `disconnect claude-desktop` removes only the owned, unmodified server entry; it preserves other settings and project state. `uninstall` handles project adapters separately.
+
+The connection writes an app-wide config containing an absolute interpreter and project path. A project-local receipt tracks ownership; a neighboring SQLite lock serializes this package's config writers. Atomic replacement handles individual writes; this is not a cross-file crash transaction. Keep the receipt to manage the connection. After moving a project, disconnect from the old location and reconnect from the new one. `doctor` checks the saved connection but cannot approve tools or certify host execution.
+
+Use the Chat surface. Cowork and Code in Desktop have different local tool rules; the tested build displayed a reserved-server-name warning for those surfaces. Chat still discovered the server. See [MCP SDK desktop setup](https://py.sdk.modelcontextprotocol.io/get-started/real-host/) and the [actual acceptance report](host-acceptance.md).
+
+### Antigravity product variants
+
+The workspace config path is documented for Antigravity IDE/CLI. Antigravity desktop 2.0 also has an Installed MCP Servers settings surface. In the live desktop test, the model did not receive the project MCP tools despite generated files and a populated tool cache; no state was generated. The separate IDE opened to login. Do not interpret these adapters as a passing test for every Antigravity product. [Official MCP configuration](https://antigravity.google/docs/mcp).
+
 1. **Generated:** expected files/configuration exist.
 2. **Validated:** managed content and configuration match.
 3. **Transport tested:** actual SDK client/server initialize/list/call succeeds (`doctor --mcp`).

skillstate_kit-0.1.2/docs/host-acceptance.md

@@ -0,0 +1,65 @@
+# Host acceptance — 2026-09-07
+
+This exercise used a new local workspace and a synthetic invoice with line totals
+10, 20 and 30 EUR. The baseline server was installed from public PyPI 0.1.1 into
+a separate, non-editable environment. New Claude Desktop connection code was
+then exercised from the development checkout. No production data was used.
+
+| Host/surface | Observation | Verdict |
+|---|---|---|
+| Installed Codex CLI, actual model | Eight successful MCP calls; invoice total and artifact persisted; owner transferred to claude-desktop | First review and handoff passed |
+| Claude Desktop 1.46388.4.0, Chat | Server discovered; actual model requested `run_context`; app displayed tool permission, then the call timed out without a result | Discovery passed; continuation failed in this attempt |
+| Claude Desktop Cowork/Code | App displayed a reserved internal server name warning for this local entry | Not supported by this tested connection |
+| Antigravity desktop, Gemini 3.8 Flash High | Opened the project; model reported MCP tools unavailable; no skill or run was created | Requested MCP task failed |
+| Separate Antigravity IDE | Login/onboarding screen, including optional migration dialog | No model task executed |
+| Claude Code standalone | Not separately exercised | No live claim |
+
+## Independently checked Codex result
+
+- Run: `desktop-acceptance-01`; revision **3**; owner `claude-desktop`.
+- Status: **ready**, no pending operation; deliberately not completed.
+- Invoice `INV-DEMO`; calculated total **60 EUR**.
+- Evidence artifact: `3324d313470e08682bd6dd9aab6ce24cc357ae4bd5de593bdd04005a4147fd60`.
+- Successful calls: `run_open`, `run_context`, `run_update`, `artifact_put`,
+  `run_context`, `run_update`, `run_context`, `run_handoff`.
+- A fresh process read the persisted run after the Codex process ended. The
+  handoff did not depend on keeping its original conversation alive.
+
+The first Codex attempt used a non-interactive policy that could not approve a
+write tool and stopped without opening a run. The successful retry used Codex's
+supported automatic review mode with a workspace-write sandbox. This is a host
+approval requirement, not permission to bypass safeguards.
+
+Claude's first tool request was not approved by the test driver. It eventually
+returned a timeout/no-result error after approximately four minutes. The UI
+suggested an unresponsive or crashed server; that explanation was not established.
+An independent `doctor --mcp` check on the same project subsequently passed.
+No second review or completion was recorded. This report does not claim a
+completed Codex-to-Claude workflow. Ordinary user tool approval remains part of
+setup. The native computer-use driver cannot grant security/privacy permissions
+on the user's behalf. Retry from the saved run after resolving host permissions;
+do not recreate or reset the run.
+
+Antigravity wrote its own final diagnostic reporting unavailable tools. Its
+local tool cache contained the 12 server schemas, but that did not prove the
+model received callable tools. This distinction matters: generated files,
+discovery caches, actual calls and task completion are separate evidence levels.
+
+## Fixes and reproducibility
+
+The exercise exposed missing Claude Desktop setup and an ambiguous `..` in the
+root source directory instruction. Version 0.1.2 adds a reversible desktop
+connection, config ownership/conflict checks, Windows Store path detection,
+doctor checks and an unambiguous source directory. Regression tests cover
+preservation, multiple projects, modified entries, config ambiguity and write
+failure rollback.
+
+The portable [sample project](../examples/desktop_acceptance/README.md) documents
+both prompts and independent state/event checks. Host behavior remains subject
+to its installed version, account, model and permissions. These observations do
+not establish paper benchmark reproduction or universal task reliability.
+
+Local validation before release included the complete test suite, the 85%
+statement/branch coverage gate, formatting/lint, wheel/sdist metadata validation,
+and a clean wheel installation with an actual 12-tool STDIO MCP handshake.
+The release workflow reruns the full OS/Python matrix before publishing.

skillstate_kit-0.1.2/docs/releases/0.1.1.md

@@ -0,0 +1,28 @@
+# 0.1.1 release evidence
+
+Published on **2026-09-07 (Europe/Istanbul)** as the first public alpha distribution. The GitHub repository remains private.
+
+- [PyPI release](https://pypi.org/project/skillstate-kit/0.1.1/)
+- [Initial publication](https://github.com/Atakan-Emre/skillstate-kit/actions/runs/34062326878), source commit `0d4ae46198dc621cf986967a6a5959942f625d6e`.
+- [Complete publishing and post-publication verification](https://github.com/Atakan-Emre/skillstate-kit/actions/runs/34062474628), workflow commit `7d7b6cd`.
+
+The latter run passed six Windows/macOS/Ubuntu and Python 3.11/3.13 jobs, distribution build and clean installation, publication recovery against existing files, and registry download/hash/installation verification. Its artifacts match the initial upload. TestPyPI was intentionally not used; no TestPyPI validation is claimed.
+
+## Local consumer verification
+
+A new Windows/Python 3.12 environment installed `skillstate-kit==0.1.1` directly from `https://pypi.org/simple` with cache disabled. The core-only installation completed the scripted demo. Installing the `mcp,http` extras then passed project initialization, source skill generation, bundle validation and a real STDIO MCP handshake with 12 tools.
+
+The local test suite passed **104 tests**, with **one skipped** because local Windows symlink privileges were unavailable. Combined package statement/branch coverage was **87.12%**. Five of these tests specifically reject substituted hashes, changed download bytes, yanked files and unexpected registry hosts before package execution.
+
+## Published file integrity
+
+Both files were downloaded from the registry and checked against the CI artifacts before the downloaded wheel was installed in another clean environment.
+
+```text
+244b4e7d392b6f22eb795b3b64ac55b89b82ebf62385704bbabd58172e1c0f6f  skillstate_kit-0.1.1-py3-none-any.whl
+9515e839e72f717f27e0ef6ee7f6d9e476d9e301d77ef77f1cdd7e982c618455  skillstate_kit-0.1.1.tar.gz
+```
+
+Publishing uses the `Atakan-Emre/skillstate-kit` repository, `publish.yml`, the `pypi` GitHub environment and short-lived OIDC credentials. The environment permits only `main`. No permanent PyPI API token was added to the repository.
+
+These checks establish the release and tested contracts. They do not establish defect-free operation, automatic native-tool interception, live task compatibility with every IDE version or a reproduction of the paper's benchmarks.

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/docs/releasing.md

@@ -13,7 +13,7 @@ The repository currently stays private. Build a wheel/sdist after the test and p
 
 ## PyPI publication
 
-PyPI publication makes distributions publicly downloadable, even if GitHub remains private. Publication has been requested for this project; the first public candidate is 0.1.1. Registry presence and workflow results, not a prepared document, establish that publication actually happened.
+PyPI publication makes distributions publicly downloadable, even if GitHub remains private. Version 0.1.1 is published; see [release evidence](releases/0.1.1.md). Registry presence and workflow results, not a prepared document, establish that a new publication actually happened.
 
 The manually dispatched `.github/workflows/publish.yml` runs the full CI matrix, builds once and verifies a clean wheel installation before uploading to PyPI. It then downloads both published distributions, verifies their SHA-256 hashes against the tested artifacts and exercises the downloaded wheel in a fresh environment. Publishing jobs alone receive `id-token: write`; they do not check out or execute project code. `skip-existing` supports interrupted-run recovery; differing registry hashes fail verification.
 

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/docs/validation.md

@@ -2,13 +2,17 @@
 
 Tests validate contracts, not an absence of all possible defects. A successful generation reports structural checks; it does not invent live execution evidence.
 
+## Desktop acceptance (2026-09-07)
+
+See [host acceptance](host-acceptance.md) for a real Codex MCP review/handoff and the observed Claude Desktop/Antigravity blockers. The original configuration-only checks below are historical and do not supersede that report.
+
 ## Initial release checks (2026-09-06)
 
 - Local Windows / Python 3.12.7: **99 passed, 1 skipped**, **87.12%** combined statement/branch coverage. The skipped test requires symlink privileges. CLI Unicode output was also verified through an ASCII-only pipe.
 - A scripted 100-operation run retained identical model-context byte sizes while its audit grew to 202 events. This checks history isolation, not real-model task quality or token savings.
 - Fresh wheel installation in a separate environment passed demo, generation, bundle validation and a real 12-tool MCP STDIO handshake (protocol `2025-11-25`). Wheel/sdist passed `twine check`.
 - Both generated skill files passed Codex's skill-format validator. The installed Codex CLI discovered the generated `skillstate-kit` MCP entry and reported it enabled. This was configuration discovery, not a live model completing the workflow.
-- Claude Code and Antigravity applications were not available for live task verification. Their generated configuration and shared state protocol are covered by automated tests.
+- Claude Code and Antigravity were not exercised as live applications in this initial check. This did not establish that the desktop applications were absent from the computer. Their generated configuration and shared state protocol were covered by automated tests.
 
 The release's CI link records the exact release commit and cross-platform results; use it when checking a downloaded distribution. These observations do not certify every host version or arbitrary generated domain schema.
 

skillstate_kit-0.1.2/examples/desktop_acceptance/README.md

@@ -0,0 +1,49 @@
+# Real host acceptance exercise
+
+Copy this directory into an empty local workspace. Use synthetic data throughout.
+The two host conversations must share the same workspace, not different worktrees.
+
+```console
+python -m pip install "skillstate-kit[mcp]"
+skillstate init --mcp
+skillstate generate SKILL.md --name invoice-audit --install
+skillstate doctor --mcp
+```
+
+For Claude Desktop **Chat**, additionally run `skillstate connect claude-desktop`
+and fully quit/reopen the app. This is separate from Claude Code and Cowork.
+Normal host tool approvals remain necessary. Do not disable host safeguards.
+
+Ask the first host:
+
+> Use the skillstate-kit MCP tools to open invoice-audit as owner codex, run ID
+> invoice-test-01. Read context, calculate the invoice total, record the facts and
+> a text evidence artifact, then hand off to owner claude-desktop. Do not complete
+> the run. Report actual tool failures instead of simulating success.
+
+Ask Claude Desktop Chat:
+
+> Use the local skillstate MCP tools to read invoice-test-01 and its evidence.
+> Independently check the arithmetic, record the second review as owner
+> claude-desktop, then complete the run if all checks pass. Report its final
+> revision, owner and status. Do not reset the run or invent tool results.
+
+Verify outside the host conversations:
+
+```console
+skillstate run context invoice-test-01
+skillstate run events invoice-test-01
+```
+
+The total must be 60 EUR, the artifact must contain the arithmetic, the owner
+must be claude-desktop, and the status must be completed. The event stream must
+show the initial review, handoff and second review. A chat answer alone does not
+prove success. If a host stops for approval, status must remain incomplete.
+
+To test generation by a host, ask it to generate a separate `invoice-semantic`
+skill from SKILL.md using `generation_prepare` and `generation_apply`, citing
+the returned source hash. Inspect the resulting schema and run it separately.
+
+Disconnect the desktop entry with `skillstate disconnect claude-desktop`.
+Run data is retained for inspection. `skillstate uninstall` only removes the
+project host files it owns; it does not disconnect the app-wide desktop entry.

skillstate_kit-0.1.2/examples/desktop_acceptance/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: invoice-audit
+description: Audit a synthetic invoice and pass verified state to another reviewer.
+---
+
+# Invoice audit
+
+This fixture contains no personal or production data.
+Invoice INV-DEMO has three line totals: 10, 20 and 30 EUR.
+
+1. Calculate the sum and record the invoice ID, currency and total in state.
+2. Store a text evidence artifact containing the arithmetic and its result.
+3. The first reviewer transfers the run to a second reviewer without completing it.
+4. The second reviewer reads the persistent context and evidence, independently
+   checks that the total is 60 EUR, and records a successful review.
+5. Complete only after the second review. Never invent an executed external tool.

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "skillstate-kit"
-version = "0.1.1"
+version = "0.1.2"
 description = "Compile existing agent skills into portable, validated execution state."
 readme = "docs/PYPI_README.md"
 requires-python = ">=3.11"

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/src/skillstate/__init__.py

@@ -15,7 +15,7 @@ from .runtime import SkillRuntime
 from .schema import apply_patch
 from .store import SQLiteStore
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"
 __all__ = [
     "BudgetExceeded",
     "ConflictError",

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/src/skillstate/cli.py

@@ -62,6 +62,10 @@ def parser() -> argparse.ArgumentParser:
     subs.add_parser("status", help="List local runs")
     subs.add_parser("demo", help="Run the explicit offline scripted-model example")
     subs.add_parser("serve", help="Start a project-scoped STDIO MCP server")
+    for command in ("connect", "disconnect"):
+        desktop = subs.add_parser(command, help=f"{command.title()} this project to Claude Desktop")
+        desktop.add_argument("host", choices=("claude-desktop",))
+        desktop.add_argument("--config", type=Path, help="Explicit desktop config path")
     run = subs.add_parser("run", help="Operate a durable run")
     r = run.add_subparsers(dest="operation", required=True)
     open_p = r.add_parser("open")
@@ -114,6 +118,10 @@ def dispatch(args) -> dict | list | None:
 
     if args.command == "init":
         return hosts.install(project, args.host, mcp=args.mcp)
+    if args.command in ("connect", "disconnect"):
+        from .desktop import connection
+
+        return connection(project, config=args.config, remove=args.command == "disconnect")
     if args.command == "generate":
         if args.prepare:
             return compiler.prepare(project, args.source, args.name)

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/src/skillstate/compiler.py

@@ -216,7 +216,7 @@ def tracking_ir(inventory: dict, name: str | None = None, profile: str = "auto")
         )
     instructions = (
         f"Source procedure: {primary['path']}. Resolve its resource paths relative to "
-        f"{Path(primary['path']).parent.as_posix()}. Follow the user's current task and authorizations.\n\n"
+        f"`{Path(primary['path']).parent.as_posix()}` within the project root. Follow the user's current task and authorizations.\n\n"
         + body
         + "\n\nTrack active_step, completed_steps, facts, blockers and artifacts. "
         "Only mark steps complete after checking their results. Retain facts needed by later steps. "

skillstate_kit-0.1.2/src/skillstate/desktop.py

@@ -0,0 +1,142 @@
+"""Explicit, reversible Claude Desktop connections to one local project."""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sqlite3
+import sys
+from contextlib import closing
+from pathlib import Path
+
+from .errors import ConflictError, ValidationError
+from .hosts import _config_document
+from .jsonio import atomic_write, digest, dumps, read_json, within
+
+
+def checks(project: Path) -> list[dict]:
+    """Inspect a saved connection; never imply that the host loaded it."""
+    receipt_path = within(project.resolve(), ".skillstate/local/claude-desktop.json")
+    if not receipt_path.exists():
+        return []
+    try:
+        receipt = read_json(receipt_path)
+        path = Path(receipt["config"])
+        doc = _config_document(path, "json")
+        matching = doc.get("mcpServers", {}).get(receipt["server_name"]) == receipt["entry"]
+        executable = Path(receipt["entry"]["command"]).is_file()
+    except (KeyError, TypeError, AttributeError, ValueError, OSError, ValidationError):
+        matching, executable = False, False
+    return [
+        {"check": "claude-desktop config", "kind": "mcp_configuration", "ok": matching},
+        {"check": "claude-desktop interpreter", "kind": "executable", "ok": executable},
+    ]
+
+
+def config_path() -> Path:
+    """Resolve standalone and Microsoft Store installs without reading credentials."""
+    if sys.platform == "win32":
+        local = os.environ.get("LOCALAPPDATA")
+        packaged = (
+            Path(local)
+            / "Packages/Claude_pzs8sxrjxfjjc/LocalCache/Roaming/Claude/claude_desktop_config.json"
+            if local
+            else None
+        )
+        roaming = os.environ.get("APPDATA")
+        regular = Path(roaming) / "Claude/claude_desktop_config.json" if roaming else None
+        existing = [p for p in (regular, packaged) if p is not None and p.is_file()]
+        if len(existing) > 1:
+            raise ValidationError("Multiple Claude Desktop configs found; select one with --config")
+        if existing:
+            return existing[0]
+        if packaged is not None and packaged.parent.is_dir():
+            return packaged
+        if regular is not None:
+            return regular
+    elif sys.platform == "darwin":
+        return Path.home() / "Library/Application Support/Claude/claude_desktop_config.json"
+    raise ValidationError("Specify the Claude Desktop config path with --config on this platform")
+
+
+def connection(project: Path, *, config: Path | None = None, remove: bool = False) -> dict:
+    """Merge only an owned project-specific server; preserve other app settings."""
+    project = project.resolve()
+    receipt_path = within(project, ".skillstate/local/claude-desktop.json")
+    receipt = read_json(receipt_path) if receipt_path.exists() else None
+    if remove and receipt is None:
+        return {"connected": False, "changed": False, "state_retained": True}
+    if receipt is not None and (
+        not isinstance(receipt, dict)
+        or set(receipt) != {"config", "server_name", "entry"}
+        or not isinstance(receipt["config"], str)
+        or not isinstance(receipt["entry"], dict)
+    ):
+        raise ValidationError("Invalid Claude Desktop connection receipt")
+    target = config or (Path(receipt["config"]) if receipt else config_path())
+    target = within(target.absolute().parent, target.absolute())
+    server_name = "skillstate-" + digest(str(project))[:12]
+    if receipt and (receipt["config"] != str(target) or receipt["server_name"] != server_name):
+        raise ConflictError("Disconnect the existing Claude Desktop connection first")
+    if not remove and importlib.util.find_spec("mcp") is None:
+        raise ValidationError("Install skillstate-kit[mcp] before connecting Claude Desktop")
+    entry = {
+        "command": sys.executable,
+        "args": ["-m", "skillstate", "--project", str(project), "serve"],
+    }
+    target.parent.mkdir(parents=True, exist_ok=True)
+    # Serialize our writers across projects and processes sharing this app config.
+    lock = within(target.parent, target.name + ".skillstate-lock.sqlite3")
+    with closing(sqlite3.connect(lock, timeout=10, isolation_level=None)) as db:
+        db.execute("BEGIN IMMEDIATE")
+        try:
+            original = target.read_bytes() if target.exists() else None
+            doc = _config_document(target, "json")
+            servers = doc.setdefault("mcpServers", {})
+            if not isinstance(servers, dict):
+                raise ValidationError("MCP config section must be an object")
+            current = servers.get(server_name)
+            if current is not None and (receipt is None or current != receipt["entry"]):
+                raise ConflictError("Refusing to change a user-owned Claude Desktop server entry")
+            if remove:
+                servers.pop(server_name, None)
+            else:
+                servers[server_name] = entry
+            updated = (dumps(doc) + "\n").encode("utf-8")
+            # Also detect non-cooperating editor writes observed since the initial read.
+            if (target.read_bytes() if target.exists() else None) != original:
+                raise ConflictError("Claude Desktop config changed during connection; retry")
+            changed = updated != original
+            if changed:
+                atomic_write(target, updated)
+            try:
+                if remove:
+                    receipt_path.unlink(missing_ok=True)
+                else:
+                    atomic_write(
+                        receipt_path,
+                        dumps({"config": str(target), "server_name": server_name, "entry": entry})
+                        + "\n",
+                    )
+            except BaseException:
+                if changed:
+                    if original is None:
+                        target.unlink(missing_ok=True)
+                    else:
+                        atomic_write(target, original)
+                raise
+            db.execute("COMMIT")
+        finally:
+            if db.in_transaction:
+                db.execute("ROLLBACK")
+    return {
+        "connected": not remove,
+        "changed": changed,
+        "host": "claude-desktop",
+        "config": str(target),
+        "server_name": server_name,
+        "project": str(project),
+        "state_retained": True,
+        "live_host_verified": False,
+        "next": "Fully quit and reopen Claude Desktop. Use Chat for local MCP, not Cowork.",
+    }

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/src/skillstate/hosts.py

@@ -268,6 +268,8 @@ def uninstall(project: Path) -> dict:
 
 
 def doctor(project: Path) -> dict:
+    from .desktop import checks as desktop_checks
+
     project = project.resolve()
     manifest = _manifest(project)
     checks = []
@@ -306,6 +308,7 @@ def doctor(project: Path) -> dict:
                 "ok": importlib.util.find_spec("mcp") is not None,
             }
         )
+    checks.extend(desktop_checks(project))
     return {
         "ok": bool(checks) and all(check["ok"] for check in checks),
         "checks": checks,

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/tests/test_compiler_hosts.py

@@ -198,6 +198,14 @@ def test_three_host_sequential_handoff_preserves_state(project):
     # This verifies our protocol, not live IDE applications.
 
 
+def test_root_skill_resource_directory_is_unambiguous(project):
+    (project / "SKILL.md").write_text("# Check\n1. Read fixtures/input.json.\n", encoding="utf-8")
+    generated = generate(project, "SKILL.md", name="root-check")
+    service = ProjectService(project)
+    opened = service.open_run(generated["name"], "codex", "root-run", {})
+    assert "relative to `.` within the project root." in opened["skill"]["instructions"]
+
+
 def test_source_drift_is_reported_and_blocks_handoff(project):
     generated = generate(project, SOURCE)
     service = ProjectService(project)

skillstate_kit-0.1.2/tests/test_desktop.py

@@ -0,0 +1,120 @@
+import json
+from concurrent.futures import ThreadPoolExecutor
+
+import pytest
+
+from skillstate import desktop
+from skillstate.cli import main
+from skillstate.errors import ConflictError, ValidationError
+from skillstate.hosts import doctor
+
+
+def test_desktop_connect_reconnect_disconnect_preserves_settings(project, tmp_path):
+    config = tmp_path / "desktop" / "claude_desktop_config.json"
+    config.parent.mkdir()
+    original = {"preferences": {"theme": "dark"}, "mcpServers": {"other": {"command": "keep"}}}
+    config.write_text(json.dumps(original))
+    first = desktop.connection(project, config=config)
+    assert first["connected"] and first["changed"]
+    assert doctor(project)["ok"]
+    assert not desktop.connection(project)["changed"]
+    value = json.loads(config.read_text())
+    entry = value["mcpServers"][first["server_name"]]
+    assert entry["args"][-2:] == [str(project.resolve()), "serve"]
+    assert value["preferences"] == original["preferences"]
+    assert value["mcpServers"]["other"] == original["mcpServers"]["other"]
+    assert not desktop.connection(project, remove=True)["connected"]
+    assert json.loads(config.read_text()) == original
+
+
+def test_desktop_refuses_user_modified_entry(project, tmp_path):
+    config = tmp_path / "desktop.json"
+    result = desktop.connection(project, config=config)
+    value = json.loads(config.read_text())
+    value["mcpServers"][result["server_name"]]["command"] = "custom"
+    config.write_text(json.dumps(value))
+    before = config.read_bytes()
+    assert not doctor(project)["ok"]
+    for remove in (False, True):
+        with pytest.raises(ConflictError):
+            desktop.connection(project, remove=remove)
+        assert config.read_bytes() == before
+
+
+def test_desktop_multiple_projects_and_config_switch(project, tmp_path):
+    config = tmp_path / "desktop.json"
+    first = desktop.connection(project, config=config)
+    second = desktop.connection(tmp_path / "second", config=config)
+    assert first["server_name"] != second["server_name"]
+    desktop.connection(project, remove=True)
+    assert list(json.loads(config.read_text())["mcpServers"]) == [second["server_name"]]
+    with pytest.raises(ConflictError):
+        desktop.connection(tmp_path / "second", config=tmp_path / "other.json")
+
+
+def test_concurrent_desktop_connections_do_not_lose_other_projects(tmp_path):
+    config = tmp_path / "desktop.json"
+    projects = [tmp_path / f"project-{i}" for i in range(4)]
+    with ThreadPoolExecutor(max_workers=4) as pool:
+        results = list(
+            pool.map(lambda project: desktop.connection(project, config=config), projects)
+        )
+    assert set(json.loads(config.read_text())["mcpServers"]) == {
+        result["server_name"] for result in results
+    }
+    assert all(desktop.checks(project)[0]["ok"] for project in projects)
+
+
+def test_desktop_receipt_failure_rolls_back_config(project, tmp_path, monkeypatch):
+    config = tmp_path / "desktop.json"
+    config.write_text('{"preferences":{"keep":true}}')
+    before = config.read_bytes()
+    real_write = desktop.atomic_write
+
+    def fail_receipt(path, content):
+        if path.name == "claude-desktop.json":
+            raise OSError("simulated receipt disk failure")
+        real_write(path, content)
+
+    monkeypatch.setattr(desktop, "atomic_write", fail_receipt)
+    with pytest.raises(OSError):
+        desktop.connection(project, config=config)
+    assert config.read_bytes() == before
+
+
+def test_desktop_windows_store_detection_and_ambiguity(tmp_path, monkeypatch):
+    monkeypatch.setattr(desktop.sys, "platform", "win32")
+    monkeypatch.setenv("APPDATA", str(tmp_path / "roaming"))
+    monkeypatch.setenv("LOCALAPPDATA", str(tmp_path / "local"))
+    packaged = (
+        tmp_path
+        / "local/Packages/Claude_pzs8sxrjxfjjc/LocalCache/Roaming/Claude/claude_desktop_config.json"
+    )
+    packaged.parent.mkdir(parents=True)
+    packaged.write_text("{}")
+    assert desktop.config_path() == packaged
+    regular = tmp_path / "roaming/Claude/claude_desktop_config.json"
+    regular.parent.mkdir(parents=True)
+    regular.write_text("{}")
+    with pytest.raises(ValidationError, match="Multiple"):
+        desktop.config_path()
+
+
+def test_desktop_cli_and_invalid_config(project, tmp_path, capsys):
+    config = tmp_path / "desktop.json"
+    prefix = ["--project", str(project)]
+    assert main(prefix + ["connect", "claude-desktop", "--config", str(config)]) == 0
+    assert json.loads(capsys.readouterr().out)["connected"]
+    assert main(prefix + ["disconnect", "claude-desktop"]) == 0
+    config.write_text('{"mcpServers":[]}')
+    with pytest.raises(ValidationError):
+        desktop.connection(project, config=config)
+
+
+def test_disconnect_without_receipt_does_not_discover_or_touch_config(project, monkeypatch):
+    monkeypatch.setattr(desktop, "config_path", lambda: pytest.fail("must not discover config"))
+    assert desktop.connection(project, remove=True) == {
+        "connected": False,
+        "changed": False,
+        "state_retained": True,
+    }

{skillstate_kit-0.1.1 → skillstate_kit-0.1.2}/uv.lock

@@ -1442,7 +1442,7 @@ wheels = [
 
 [[package]]
 name = "skillstate-kit"
-version = "0.1.1"
+version = "0.1.2"
 source = { editable = "." }
 dependencies = [
     { name = "jsonschema" },