workstate-protocol 0.1.5__tar.gz → 0.1.7__tar.gz

{workstate_protocol-0.1.5 → workstate_protocol-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workstate-protocol
-Version: 0.1.5
+Version: 0.1.7
 Summary: Typed cross-repo contracts for the Workstate system: handoff state, MCP I/O, hook events, skill manifests, bootstrap install manifest.
 License: MIT
 Project-URL: Homepage, https://github.com/darce/workstate

{workstate_protocol-0.1.5 → workstate_protocol-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "workstate-protocol"
-version = "0.1.5"
+version = "0.1.7"
 description = "Typed cross-repo contracts for the Workstate system: handoff state, MCP I/O, hook events, skill manifests, bootstrap install manifest."
 readme = "README.md"
 requires-python = ">=3.11"

{workstate_protocol-0.1.5 → workstate_protocol-0.1.7}/src/workstate_protocol/__init__.py

@@ -32,20 +32,36 @@ from .hooks import (
     StopEvent,
     UserPromptSubmitEvent,
 )
+from .paths import (
+    CONTRACTS_DIR,
+    DOCS_MIRROR_DIR,
+    HARNESS_CONTRACT_RELPATH,
+    INSTRUCTIONS_RELPATH,
+    RULES_DIR,
+    RUNTIME_ROOT_DIRNAME,
+    docs_mirror_path,
+    runtime_root_path,
+)
 from .skills import SkillManifest, SkillScope
 
-__version__ = "0.1.5"
+__version__ = "0.1.6"
 
 __all__ = [
     "ActiveTask",
     "BootstrapManifest",
+    "CONTRACTS_DIR",
+    "DOCS_MIRROR_DIR",
     "DecisionRef",
+    "HARNESS_CONTRACT_RELPATH",
     "HandoffState",
     "HandoffStatus",
+    "INSTRUCTIONS_RELPATH",
     "OverlayConfigEntry",
     "OverlaySurface",
     "PostToolUseEvent",
     "PreToolUseEvent",
+    "RULES_DIR",
+    "RUNTIME_ROOT_DIRNAME",
     "SessionStartEvent",
     "SkillManifest",
     "SkillScope",
@@ -61,6 +77,8 @@ __all__ = [
     "__version__",
     "branch_naming",
     "derive_task_ref_candidates",
+    "docs_mirror_path",
     "format_suggested_branch_name",
     "resolve_env_alias",
+    "runtime_root_path",
 ]

{workstate_protocol-0.1.5 → workstate_protocol-0.1.7}/src/workstate_protocol/bootstrap.py

@@ -27,7 +27,9 @@ class OverlaySurface(BaseModel):
 
     model_config = ConfigDict(extra="allow")
 
-    path: str = Field(description="Repo-relative surface path (e.g. '.claude/skills/handoff-lifecycle').")
+    path: str = Field(
+        description="Repo-relative surface path (e.g. '.claude/skills/handoff-lifecycle')."
+    )
     source: Literal["shared", "local", "overlapping", "generated", "lifecycle"] = Field(
         description=(
             "Origin tier: 'shared' (symlinked from workstate-system), "
@@ -112,7 +114,9 @@ class PluginOverrideManifest(BaseModel):
 
     schema_version: Literal[1] = 1
     plugin: PluginComponentName
-    components: PluginOverrideComponents = Field(default_factory=PluginOverrideComponents)
+    components: PluginOverrideComponents = Field(
+        default_factory=PluginOverrideComponents
+    )
 
 
 class ReplaceCommandOp(BaseModel):
@@ -240,10 +244,24 @@ class BootstrapManifest(BaseModel):
     model_config = ConfigDict(extra="allow")
 
     schema_version: int = Field(ge=1, description="Manifest schema version.")
-    remote_url: str = Field(min_length=1)
-    remote_ref: str = Field(min_length=1)
-    remote_sha: Sha40 = Field(
-        description="Resolved 40-char git SHA at install time.",
+    source_kind: Literal["git_overlay", "package"] = Field(
+        default="git_overlay",
+        description=(
+            "Overlay delivery source: 'git_overlay' (a clone checked out at "
+            "remote_ref) or 'package' (an installed workstate-system "
+            "distribution). Defaults to 'git_overlay' so manifests written "
+            "before WS-PKG-DELIVERY-01 validate unchanged."
+        ),
+    )
+    remote_url: str | None = Field(default=None, min_length=1)
+    remote_ref: str | None = Field(default=None, min_length=1)
+    remote_sha: Sha40 | None = Field(
+        default=None,
+        description="Resolved 40-char git SHA at install time (git_overlay source).",
+    )
+    package_version: str | None = Field(
+        default=None,
+        description="Installed workstate-system distribution version (package source).",
     )
     surfaces: list[OverlaySurface] = Field(default_factory=list)
     configs: list[OverlayConfigEntry] = Field(default_factory=list)
@@ -265,3 +283,23 @@ class BootstrapManifest(BaseModel):
             "override location."
         ),
     )
+
+    @model_validator(mode="after")
+    def _check_source_provenance(self) -> "BootstrapManifest":
+        """Each delivery source requires its own provenance fields.
+
+        ``git_overlay`` (the default, so pre-WS-PKG-DELIVERY-01 manifests keep
+        validating) requires the git ``remote_*`` triple; ``package`` requires
+        the installed distribution ``package_version``.
+        """
+        if self.source_kind == "git_overlay":
+            missing = [
+                name
+                for name in ("remote_url", "remote_ref", "remote_sha")
+                if not getattr(self, name)
+            ]
+            if missing:
+                raise ValueError("git_overlay manifest requires " + ", ".join(missing))
+        elif self.source_kind == "package" and not self.package_version:
+            raise ValueError("package manifest requires package_version")
+        return self

workstate_protocol-0.1.7/src/workstate_protocol/env_aliases.py

@@ -0,0 +1,54 @@
+"""Canonical Workstate env-var resolution helpers."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from typing import overload
+
+__all__ = ["resolve_env_alias"]
+
+
+def _non_empty(value: str | None) -> str | None:
+    if value is None:
+        return None
+    stripped = value.strip()
+    return stripped or None
+
+
+@overload
+def resolve_env_alias(
+    canonical: str,
+    *,
+    env: Mapping[str, str] | None = ...,
+    default: str,
+) -> str: ...
+
+
+@overload
+def resolve_env_alias(
+    canonical: str,
+    *,
+    env: Mapping[str, str] | None = ...,
+    default: None = ...,
+) -> str | None: ...
+
+
+def resolve_env_alias(
+    canonical: str,
+    *,
+    env: Mapping[str, str] | None = None,
+    default: str | None = None,
+) -> str | None:
+    """Resolve a canonical Workstate env var.
+
+    Blank/whitespace-only values are treated as unset, matching the existing
+    ``_first_non_empty_env`` behaviour in the handoff package.
+    """
+
+    source = os.environ if env is None else env
+
+    canonical_value = _non_empty(source.get(canonical))
+    if canonical_value is not None:
+        return canonical_value
+    return default

workstate_protocol-0.1.7/src/workstate_protocol/paths.py

@@ -0,0 +1,48 @@
+"""Canonical Workstate runtime + doc-mirror path roots — single source of truth.
+
+The runtime install directory is ``.workstate/`` and the mirrored docs/contracts
+path is ``docs/workstate/``. Every package resolves these through this module so
+the names live in exactly one place: a future path change is a one-line flip
+here, not a repo-wide sweep.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# Runtime install root — bootstrap materializes overlay surfaces and the remote
+# clone under ``<target>/.workstate/``.
+RUNTIME_ROOT_DIRNAME = ".workstate"
+
+# Mirrored docs / contracts path — the SHARED_SURFACES consumed at install time
+# (rules, contracts, templates) live under ``docs/workstate/``.
+DOCS_MIRROR_DIR = "docs/workstate"
+
+# Common derived locations under the canonical docs mirror.
+CONTRACTS_DIR = f"{DOCS_MIRROR_DIR}/contracts"
+RULES_DIR = f"{DOCS_MIRROR_DIR}/rules"
+HARNESS_CONTRACT_RELPATH = Path(CONTRACTS_DIR) / "harness-protocol.yaml"
+INSTRUCTIONS_RELPATH = Path(DOCS_MIRROR_DIR) / "instructions.md"
+
+__all__ = [
+    "CONTRACTS_DIR",
+    "DOCS_MIRROR_DIR",
+    "HARNESS_CONTRACT_RELPATH",
+    "INSTRUCTIONS_RELPATH",
+    "RULES_DIR",
+    "RUNTIME_ROOT_DIRNAME",
+    "docs_mirror_path",
+    "runtime_root_path",
+]
+
+
+def docs_mirror_path(*parts: str) -> Path:
+    """Return a path under the canonical docs mirror (``docs/workstate/...``)."""
+
+    return Path(DOCS_MIRROR_DIR, *parts)
+
+
+def runtime_root_path(base: Path, *parts: str) -> Path:
+    """Return a path under ``<base>/.workstate/...``."""
+
+    return base.joinpath(RUNTIME_ROOT_DIRNAME, *parts)

{workstate_protocol-0.1.5 → workstate_protocol-0.1.7}/src/workstate_protocol.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workstate-protocol
-Version: 0.1.5
+Version: 0.1.7
 Summary: Typed cross-repo contracts for the Workstate system: handoff state, MCP I/O, hook events, skill manifests, bootstrap install manifest.
 License: MIT
 Project-URL: Homepage, https://github.com/darce/workstate

{workstate_protocol-0.1.5 → workstate_protocol-0.1.7}/src/workstate_protocol.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ src/workstate_protocol/compaction.py
 src/workstate_protocol/env_aliases.py
 src/workstate_protocol/handoff.py
 src/workstate_protocol/hooks.py
+src/workstate_protocol/paths.py
 src/workstate_protocol/py.typed
 src/workstate_protocol/skills.py
 src/workstate_protocol.egg-info/PKG-INFO

workstate_protocol-0.1.7/tests/test_env_aliases.py

@@ -0,0 +1,39 @@
+"""Tests for canonical Workstate env-var reads."""
+
+from __future__ import annotations
+
+import pytest
+
+from workstate_protocol import resolve_env_alias
+from workstate_protocol import env_aliases
+
+
+def test_canonical_name_wins():
+    env = {"WORKSTATE_STATE_DIR": "/new", "AGENT_HANDOFF_STATE_DIR": "/old"}
+    value = resolve_env_alias("WORKSTATE_STATE_DIR", env=env)
+    assert value == "/new"
+
+
+def test_legacy_name_is_ignored():
+    env = {"AGENT_HANDOFF_STATE_DIR": "/old"}
+    assert resolve_env_alias("WORKSTATE_STATE_DIR", env=env) is None
+
+
+def test_legacy_args_are_not_supported():
+    with pytest.raises(TypeError):
+        resolve_env_alias("WORKSTATE_STATE_DIR", "AGENT_HANDOFF_STATE_DIR", env={})
+
+
+def test_warn_once_reset_hook_is_removed():
+    assert not hasattr(env_aliases, "reset_alias_warnings")
+
+
+def test_blank_canonical_returns_default_not_legacy():
+    env = {"WORKSTATE_STATE_DIR": "   ", "AGENT_HANDOFF_STATE_DIR": "/old"}
+    value = resolve_env_alias("WORKSTATE_STATE_DIR", env=env, default="/fallback")
+    assert value == "/fallback"
+
+
+def test_unset_returns_default():
+    assert resolve_env_alias("WORKSTATE_STATE_DIR", env={}) is None
+    assert resolve_env_alias("WORKSTATE_STATE_DIR", env={}, default="/fallback") == "/fallback"

{workstate_protocol-0.1.5 → workstate_protocol-0.1.7}/tests/test_plugin_override_schema.py

@@ -111,7 +111,7 @@ def test_lock_models_roundtrip() -> None:
             "schema_version": 1,
             "plugin": "workstate-system",
             "base_remote_sha": "d" * 40,
-            "effective_root": ".agentic/generated/plugins/workstate-system/effective/claude",
+            "effective_root": ".workstate/generated/plugins/workstate-system/effective/claude",
             "components": [
                 {
                     "component_kind": "skill",

{workstate_protocol-0.1.5 → workstate_protocol-0.1.7}/tests/test_skill_manifest_real_skills.py

@@ -28,12 +28,12 @@ def _resolve_skills_root() -> pathlib.Path | None:
     """Locate ``packages/workstate-system/skills`` robustly.
 
     Resolution order:
-    1. ``AGENTIC_SYSTEM_SKILLS_ROOT`` env var override.
+    1. ``WORKSTATE_SYSTEM_SKILLS_ROOT`` env var override.
     2. Walk up from this file looking for a sibling
        ``packages/workstate-system`` directory.
     3. Sibling-package fallback two levels up.
     """
-    env_override = os.environ.get("AGENTIC_SYSTEM_SKILLS_ROOT")
+    env_override = os.environ.get("WORKSTATE_SYSTEM_SKILLS_ROOT")
     if env_override:
         candidate = pathlib.Path(env_override).expanduser()
         return candidate if candidate.is_dir() else None

workstate_protocol-0.1.5/src/workstate_protocol/env_aliases.py

@@ -1,97 +0,0 @@
-"""Tier-4 env-var alias resolution for the Workstate rebrand.
-
-implementation note Slice C / B4. During the one-release cutover from the legacy
-``AGENT_HANDOFF_*`` / ``AGENT_ORCHESTRATOR_*`` / ``AGENTIC_*`` /
-``MCP_AGENT_HANDOFF_*`` env-var names to the canonical ``WORKSTATE_*`` prefix,
-:func:`resolve_env_alias` reads the new name first, then falls back to any
-legacy alias, emitting exactly one :class:`DeprecationWarning` per legacy name
-that is actually read. The write side (exports, generated config) always sets
-the new ``WORKSTATE_*`` name only — this module is read-side compatibility so
-existing shells / CI that still export the old names keep working through the
-cutover release, with a nudge to migrate.
-"""
-
-from __future__ import annotations
-
-import os
-import warnings
-from collections.abc import Mapping
-from typing import overload
-
-__all__ = ["resolve_env_alias", "reset_alias_warnings"]
-
-# Legacy names already warned about, so the deprecation nudge fires once per
-# process regardless of how many call sites read the same var.
-_warned_legacy: set[str] = set()
-
-
-def reset_alias_warnings() -> None:
-    """Clear the warn-once ledger. Intended for tests."""
-
-    _warned_legacy.clear()
-
-
-def _non_empty(value: str | None) -> str | None:
-    if value is None:
-        return None
-    stripped = value.strip()
-    return stripped or None
-
-
-@overload
-def resolve_env_alias(
-    canonical: str,
-    *legacy: str,
-    env: Mapping[str, str] | None = ...,
-    default: str,
-) -> str: ...
-
-
-@overload
-def resolve_env_alias(
-    canonical: str,
-    *legacy: str,
-    env: Mapping[str, str] | None = ...,
-    default: None = ...,
-) -> str | None: ...
-
-
-def resolve_env_alias(
-    canonical: str,
-    *legacy: str,
-    env: Mapping[str, str] | None = None,
-    default: str | None = None,
-) -> str | None:
-    """Resolve an env var across its canonical and legacy alias names.
-
-    Precedence: the canonical ``WORKSTATE_*`` name wins when set to a
-    non-blank value. Otherwise the first non-blank legacy alias (in the order
-    given) is returned, and a :class:`DeprecationWarning` is emitted once per
-    process for that legacy name, naming the ``canonical`` replacement. When
-    nothing is set, ``default`` is returned.
-
-    Blank/whitespace-only values are treated as unset, matching the existing
-    ``_first_non_empty_env`` behaviour in the handoff package.
-    """
-
-    source = os.environ if env is None else env
-
-    canonical_value = _non_empty(source.get(canonical))
-    if canonical_value is not None:
-        return canonical_value
-
-    for name in legacy:
-        legacy_value = _non_empty(source.get(name))
-        if legacy_value is not None:
-            if name not in _warned_legacy:
-                _warned_legacy.add(name)
-                warnings.warn(
-                    f"Environment variable {name} is deprecated; "
-                    f"set {canonical} instead. The legacy name is read for "
-                    f"one release and will be removed.",
-                    DeprecationWarning,
-                    stacklevel=2,
-                )
-            return legacy_value
-
-    return default

workstate_protocol-0.1.5/tests/test_env_aliases.py

@@ -1,98 +0,0 @@
-"""Tests for the Tier-4 env-var alias shim.
-
-implementation note Slice C / B4: ``workstate_protocol.env_aliases`` resolves the
-canonical ``WORKSTATE_*`` env-var name first, then falls back to any legacy
-alias (``AGENT_HANDOFF_*`` / ``AGENT_ORCHESTRATOR_*`` / ``AGENTIC_*`` /
-``MCP_AGENT_HANDOFF_*``) for one release, emitting exactly one
-``DeprecationWarning`` per legacy name that is actually read. Exports always
-set the new name only; this shim is read-side compatibility during cutover.
-"""
-
-from __future__ import annotations
-
-import warnings
-
-import pytest
-
-from workstate_protocol import resolve_env_alias
-from workstate_protocol.env_aliases import reset_alias_warnings
-
-
-@pytest.fixture(autouse=True)
-def _clean_warn_state():
-    reset_alias_warnings()
-    yield
-    reset_alias_warnings()
-
-
-def test_canonical_name_wins_without_warning():
-    env = {"WORKSTATE_STATE_DIR": "/new", "AGENT_HANDOFF_STATE_DIR": "/old"}
-    with warnings.catch_warnings():
-        warnings.simplefilter("error", DeprecationWarning)
-        value = resolve_env_alias(
-            "WORKSTATE_STATE_DIR", "AGENT_HANDOFF_STATE_DIR", env=env
-        )
-    assert value == "/new"
-
-
-def test_legacy_fallback_emits_one_deprecation_warning():
-    env = {"AGENT_HANDOFF_STATE_DIR": "/old"}
-    with warnings.catch_warnings(record=True) as caught:
-        warnings.simplefilter("always", DeprecationWarning)
-        value = resolve_env_alias(
-            "WORKSTATE_STATE_DIR", "AGENT_HANDOFF_STATE_DIR", env=env
-        )
-    assert value == "/old"
-    dep = [w for w in caught if issubclass(w.category, DeprecationWarning)]
-    assert len(dep) == 1
-    msg = str(dep[0].message)
-    # The warning must name both the deprecated and the canonical replacement.
-    assert "AGENT_HANDOFF_STATE_DIR" in msg
-    assert "WORKSTATE_STATE_DIR" in msg
-
-
-def test_warn_once_per_legacy_name():
-    env = {"AGENT_HANDOFF_STATE_DIR": "/old"}
-    with warnings.catch_warnings(record=True) as caught:
-        warnings.simplefilter("always", DeprecationWarning)
-        first = resolve_env_alias(
-            "WORKSTATE_STATE_DIR", "AGENT_HANDOFF_STATE_DIR", env=env
-        )
-        second = resolve_env_alias(
-            "WORKSTATE_STATE_DIR", "AGENT_HANDOFF_STATE_DIR", env=env
-        )
-    assert first == second == "/old"
-    dep = [w for w in caught if issubclass(w.category, DeprecationWarning)]
-    assert len(dep) == 1
-
-
-def test_first_present_legacy_wins_among_multiple_aliases():
-    env = {"AGENTIC_LANE_ID": "lane-2"}
-    value = resolve_env_alias(
-        "WORKSTATE_LANE_ID", "AGENT_HANDOFF_LANE_ID", "AGENTIC_LANE_ID", env=env
-    )
-    assert value == "lane-2"
-
-
-def test_blank_canonical_falls_back_to_legacy():
-    env = {"WORKSTATE_STATE_DIR": "   ", "AGENT_HANDOFF_STATE_DIR": "/old"}
-    value = resolve_env_alias("WORKSTATE_STATE_DIR", "AGENT_HANDOFF_STATE_DIR", env=env)
-    assert value == "/old"
-
-
-def test_unset_returns_default_without_warning():
-    with warnings.catch_warnings():
-        warnings.simplefilter("error", DeprecationWarning)
-        assert (
-            resolve_env_alias("WORKSTATE_STATE_DIR", "AGENT_HANDOFF_STATE_DIR", env={})
-            is None
-        )
-        assert (
-            resolve_env_alias(
-                "WORKSTATE_STATE_DIR",
-                "AGENT_HANDOFF_STATE_DIR",
-                env={},
-                default="/fallback",
-            )
-            == "/fallback"
-        )