workstate-protocol 0.1.5__py3-none-any.whl

workstate_protocol/__init__.py

@@ -0,0 +1,66 @@
+"""workstate-protocol: typed cross-repo contracts for the Workstate system.
+
+Pydantic v2 models that consumer packages (mcp-workstate-handoff,
+mcp-workstate-orchestrator, workstate-bootstrap, workstate-system) import to
+guarantee wire-level compatibility across out-of-process boundaries.
+"""
+
+from __future__ import annotations
+
+from . import branch_naming as branch_naming  # re-exported submodule
+from .bootstrap import BootstrapManifest, OverlayConfigEntry, OverlaySurface
+from .branch_naming import (
+    TASK_REF_RE,
+    derive_task_ref_candidates,
+    format_suggested_branch_name,
+)
+from .compaction import DecisionRef, StructuredSummary, TurnRange
+from .env_aliases import resolve_env_alias
+from .handoff import (
+    ActiveTask,
+    HandoffState,
+    HandoffStatus,
+    TargetWorktree,
+    TaskPlanRef,
+    TaskPlanResolution,
+    TaskRef,
+)
+from .hooks import (
+    PostToolUseEvent,
+    PreToolUseEvent,
+    SessionStartEvent,
+    StopEvent,
+    UserPromptSubmitEvent,
+)
+from .skills import SkillManifest, SkillScope
+
+__version__ = "0.1.5"
+
+__all__ = [
+    "ActiveTask",
+    "BootstrapManifest",
+    "DecisionRef",
+    "HandoffState",
+    "HandoffStatus",
+    "OverlayConfigEntry",
+    "OverlaySurface",
+    "PostToolUseEvent",
+    "PreToolUseEvent",
+    "SessionStartEvent",
+    "SkillManifest",
+    "SkillScope",
+    "StopEvent",
+    "StructuredSummary",
+    "TASK_REF_RE",
+    "TargetWorktree",
+    "TaskPlanRef",
+    "TaskPlanResolution",
+    "TaskRef",
+    "TurnRange",
+    "UserPromptSubmitEvent",
+    "__version__",
+    "branch_naming",
+    "derive_task_ref_candidates",
+    "format_suggested_branch_name",
+    "resolve_env_alias",
+]

workstate_protocol/bootstrap.py

@@ -0,0 +1,267 @@
+"""Bootstrap install manifest schema (Schema #5 from founding implementation note).
+
+The wire shape ``workstate-bootstrap`` writes to
+``<target>/.workstate-overlay.json``. Captures the contract between
+bootstrap and target repos so target-side guardrails (lint hoisted
+paths, harness sync check, drift detectors) can validate against a
+single typed shape rather than per-key heuristics.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints, model_validator
+
+
+Sha40 = Annotated[str, StringConstraints(pattern=r"^[0-9a-f]{40}$")]
+Sha256Digest = Annotated[str, StringConstraints(pattern=r"^sha256:[0-9a-f]{64}$")]
+PluginComponentName = Annotated[
+    str,
+    StringConstraints(pattern=r"^[A-Za-z0-9][A-Za-z0-9._-]*$"),
+]
+
+
+class OverlaySurface(BaseModel):
+    """A single overlay surface entry (e.g. skills, commands, hooks)."""
+
+    model_config = ConfigDict(extra="allow")
+
+    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), "
+            "'local' (target-owned), 'overlapping' (target overrides shared), "
+            "'generated' (per-agent surface produced by generate_agent_workflows.py "
+            "during install — implementation note step 1), "
+            "'lifecycle' (implementation note hoisted Make fragment + runner package "
+            "— copied, not symlinked, so the consumer can run `make context` "
+            "without the workstate-system packaging tree)."
+        ),
+    )
+
+
+class OverlayConfigEntry(BaseModel):
+    """A consumer-tool config that bootstrap wrote (e.g. .vscode/mcp.json).
+
+    ``action`` is the string the install flow emits today
+    (``created``, ``updated``, ``set``, ``unchanged``). Modeled as a
+    free string rather than a Literal so the contract does not block
+    bootstrap from introducing new actions before the protocol bumps.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    path: str
+    action: str = Field(
+        min_length=1,
+        description="What bootstrap did to the config (e.g. 'created', 'updated', 'set', 'unchanged').",
+    )
+
+
+class PluginSkillOverride(BaseModel):
+    """Override contract for one plugin skill body."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    mode: Literal["replace", "disable", "add"]
+    path: str | None = None
+    upstream_digest: Sha256Digest | None = None
+    on_upstream_change: Literal["warn", "error", "ignore"] | None = None
+
+    @model_validator(mode="after")
+    def validate_mode_fields(self) -> PluginSkillOverride:
+        if self.mode in {"replace", "add"} and not self.path:
+            raise ValueError("path is required when mode is replace or add")
+        if self.mode == "replace" and self.upstream_digest is None:
+            raise ValueError("upstream_digest is required when mode is replace")
+        return self
+
+
+class PluginMcpServerOverride(BaseModel):
+    """Override contract for one MCP server entry in the plugin manifest."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    mode: Literal["patch", "disable", "add"]
+    patch_path: str | None = None
+    requires_trust_ack: bool = False
+
+    @model_validator(mode="after")
+    def validate_mode_fields(self) -> PluginMcpServerOverride:
+        if self.mode in {"patch", "add"} and not self.patch_path:
+            raise ValueError("patch_path is required when mode is patch or add")
+        return self
+
+
+class PluginOverrideComponents(BaseModel):
+    """Declared override components grouped by plugin surface kind."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    skills: dict[PluginComponentName, PluginSkillOverride] = Field(default_factory=dict)
+    mcp_servers: dict[PluginComponentName, PluginMcpServerOverride] = Field(
+        default_factory=dict
+    )
+
+
+class PluginOverrideManifest(BaseModel):
+    """Tracked, repo-owned plugin override manifest."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: Literal[1] = 1
+    plugin: PluginComponentName
+    components: PluginOverrideComponents = Field(default_factory=PluginOverrideComponents)
+
+
+class ReplaceCommandOp(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    op: Literal["replace_command"]
+    value: str = Field(min_length=1)
+
+
+class ReplaceArgsOp(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    op: Literal["replace_args"]
+    value: list[str] = Field(min_length=1)
+
+
+class AppendArgsOp(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    op: Literal["append_args"]
+    value: list[str] = Field(min_length=1)
+
+
+class UpsertEnvOp(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    op: Literal["upsert_env"]
+    name: PluginComponentName
+    value: str
+
+
+class RemoveEnvOp(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    op: Literal["remove_env"]
+    name: PluginComponentName
+
+
+class DisableServerOp(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    op: Literal["disable_server"]
+
+
+PluginMcpPatchOperation = Annotated[
+    ReplaceCommandOp
+    | ReplaceArgsOp
+    | AppendArgsOp
+    | UpsertEnvOp
+    | RemoveEnvOp
+    | DisableServerOp,
+    Field(discriminator="op"),
+]
+
+
+class PluginMcpServerPatch(BaseModel):
+    """Typed patch grammar for MCP server mutations in consumer overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: Literal[1] = 1
+    target_server: PluginComponentName
+    ops: list[PluginMcpPatchOperation] = Field(min_length=1)
+
+
+class PluginOverrideLockEntry(BaseModel):
+    """Tracked provenance for one consumer-owned plugin override."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    component_kind: Literal["skill", "command", "mcp_server"]
+    name: PluginComponentName
+    mode: Literal["replace", "disable", "add", "patch"]
+    local_path: str | None = None
+    patch_path: str | None = None
+    upstream_digest: Sha256Digest | None = None
+
+
+class PluginOverrideLock(BaseModel):
+    """Source-controlled lockfile for plugin overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: Literal[1] = 1
+    plugin: PluginComponentName
+    base_remote_sha: Sha40
+    components: list[PluginOverrideLockEntry] = Field(default_factory=list)
+
+
+class PluginEffectiveLockEntry(BaseModel):
+    """Generated receipt entry for one component in the effective plugin tree."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    component_kind: Literal["skill", "command", "mcp_server"]
+    name: PluginComponentName
+    mode: Literal["replace", "disable", "add", "patch"]
+    effective_digest: Sha256Digest
+    status: Literal["stale"] | None = None
+    override_path: str | None = None
+    recorded_upstream_digest: Sha256Digest | None = None
+    current_base_digest: Sha256Digest | None = None
+
+
+class PluginEffectiveLock(BaseModel):
+    """Generated receipt describing the composed effective plugin tree."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: Literal[1] = 1
+    plugin: PluginComponentName
+    base_remote_sha: Sha40
+    effective_root: str = Field(min_length=1)
+    components: list[PluginEffectiveLockEntry] = Field(default_factory=list)
+
+
+class BootstrapManifest(BaseModel):
+    """Top-level shape of ``.workstate-overlay.json``.
+
+    Validated on write by ``workstate-bootstrap.install`` so the file
+    cannot drift silently. Consumers (drift detectors, doctor commands)
+    parse the same model on read.
+    """
+
+    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.",
+    )
+    surfaces: list[OverlaySurface] = Field(default_factory=list)
+    configs: list[OverlayConfigEntry] = Field(default_factory=list)
+    mcp_servers: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Sorted list of managed MCP server names bootstrap last wrote "
+            "into ``.mcp.json`` / ``.vscode/mcp.json`` / ``.codex/config.toml``. "
+            "Read by ``sync_mcp_configs(prune_removed_managed=True)`` as the "
+            "authoritative previously-managed provenance so third-party "
+            "launchers in those files are preserved across syncs."
+        ),
+    )
+    plugin_overrides_path: str | None = Field(
+        default=None,
+        description=(
+            "Optional explicit plugin override root recorded by bootstrap so "
+            "later doctor/update/repair runs can reuse a non-default WORKSTATE-REF-03 "
+            "override location."
+        ),
+    )

workstate_protocol/branch_naming.py

@@ -0,0 +1,221 @@
+"""Canonical feature-branch naming rule.
+
+This module is the SOLE owner of ``TASK_REF_RE``,
+``derive_task_ref_candidates`` and ``format_suggested_branch_name``.
+Every gate (post-checkout warn, PreToolUse block, pre-commit hard gate,
+pre-push mirror) imports from here. ``workstate_handoff_mcp`` re-exports
+the same objects without redefinition. See implementation note for context.
+
+Case convention
+---------------
+
+Branches are lowercase (``feature/WORKSTATE-37-foo``). Task refs in the
+Workstate handoff task table are uppercase (``WORKSTATE-REF-37``).
+``derive_task_ref_candidates`` returns lowercase candidates; callers
+``.upper()`` each candidate before intersecting against the live task
+table. ``format_suggested_branch_name`` accepts task refs in either
+case and lowercases its output so the formatted suggestion always
+matches ``TASK_REF_RE``.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+__all__ = [
+    "BRANCH_GRAMMAR_REGISTRY",
+    "BranWORKSTATElassification",
+    "BranchGrammarEntry",
+    "TASK_REF_RE",
+    "__protocol_version__",
+    "classify_branch",
+    "derive_task_ref_candidates",
+    "format_suggested_branch_name",
+    "is_allowed_branch",
+    "select_task_ref_candidate",
+]
+
+__protocol_version__ = "1"
+
+
+TASK_REF_RE: re.Pattern[str] = re.compile(
+    r"^feature/"
+    # Task ref must start with a letter so leading-digit segments
+    # ("123-foo") and leading hyphens ("-x") are rejected.
+    r"(?=[a-z])"
+    # Must contain at least one digit somewhere in the matched group so
+    # purely alphabetic refs ("foo-bar", "no-digits-here") are rejected.
+    r"(?=[a-z0-9-]*\d)"
+    # >=2 hyphen-separated lowercase / digit segments; each segment is
+    # non-empty. The alternation enforces a `<prefix>-<rest>` shape so
+    # single-word branches like ``feature/foo`` are rejected and
+    # conventional task refs (``feature/WORKSTATE-37``,
+    # ``feature/maint-dirty-br-01``) still match.
+    r"(?P<task_ref>[a-z0-9]+(?:-[a-z0-9]+)+)"
+    r"$"
+)
+
+
+def derive_task_ref_candidates(branch_name: str) -> list[str]:
+    """Return the lowercase candidate task refs implied by a branch name.
+
+    Returns an empty list for non-conforming branch names. For
+    conforming names the algorithm walks progressively shorter prefixes
+    of the matched ``task_ref`` group, dropping prefixes that no longer
+    contain a digit. Callers ``.upper()`` each candidate before
+    intersecting against the live task table.
+
+    Examples
+    --------
+    >>> derive_task_ref_candidates("feature/WORKSTATE-37-branch-naming-enforcement")
+    ['WORKSTATE-37-branch-naming-enforcement', 'WORKSTATE-37']
+    >>> derive_task_ref_candidates("feature/maint-dirty-br-01")
+    ['maint-dirty-br-01', 'maint-dirty-br']
+    >>> derive_task_ref_candidates("fix/foo")
+    []
+    """
+    match = TASK_REF_RE.match(branch_name)
+    if match is None:
+        return []
+    full = match.group("task_ref")
+    segments = full.split("-")
+    candidates: list[str] = []
+    for end in range(len(segments), 0, -1):
+        candidate = "-".join(segments[:end])
+        if not _has_digit(candidate):
+            # Once we drop below the digit-bearing prefix, every shorter
+            # prefix is also digit-less and would never intersect with
+            # the live task table — stop walking.
+            break
+        candidates.append(candidate)
+    return candidates
+
+
+def select_task_ref_candidate(
+    branch_name: str,
+    known_task_refs: Iterable[str] | None = None,
+) -> str | None:
+    """Return the canonical UPPERCASE task ref for a branch.
+
+    - If ``known_task_refs`` is non-empty, returns the **first** candidate
+      from :func:`derive_task_ref_candidates` (longest-to-shortest) whose
+      uppercase form appears in ``known_task_refs``. This is the
+      "most-specific registered candidate wins" rule that lets
+      ``feature/<base>-<n>-fu-...`` branches resolve to the follow-up ref
+      when both the base and the follow-up are registered. When the
+      registry is non-empty but no candidate intersects, returns
+      ``None`` — the strict invariant is that we never name a candidate
+      that is absent from a populated registry (WORKSTATE65-BR-02).
+    - If ``known_task_refs`` is empty or ``None`` (no registry context
+      available at all), falls back to the shortest digit-bearing
+      prefix. This is the no-context degradation path that keeps
+      environments without a configured registry resolving identically
+      to the historical lifecycle mirror.
+    - Returns ``None`` when ``branch_name`` is non-conforming (no
+      candidates derivable).
+    """
+    candidates = derive_task_ref_candidates(branch_name)
+    if not candidates:
+        return None
+    if known_task_refs is None:
+        return candidates[-1].upper()
+    known_upper = {ref.upper() for ref in known_task_refs}
+    if not known_upper:
+        return candidates[-1].upper()
+    for candidate in candidates:
+        if candidate.upper() in known_upper:
+            return candidate.upper()
+    return None
+
+
+def format_suggested_branch_name(task_ref: str | None, *, slug: str | None = None) -> str | None:
+    """Render a "did you mean ..." branch suggestion for a task ref.
+
+    Returns ``feature/<task-ref>`` (with optional ``-<slug>``) lowercased
+    so the result is guaranteed to match ``TASK_REF_RE``. When
+    ``task_ref`` is empty / ``None`` (cold-start before ``task-start``),
+    returns ``None`` so the caller can fall back to a generic message
+    instead of crashing.
+    """
+    if not task_ref:
+        return None
+    base = f"feature/{task_ref.lower()}"
+    if slug:
+        base = f"{base}-{slug.lower()}"
+    return base
+
+
+def _has_digit(value: str) -> bool:
+    return any(ch.isdigit() for ch in value)
+
+
+# ---------------------------------------------------------------------------
+# Branch grammar registry (implementation note implementation note)
+# ---------------------------------------------------------------------------
+#
+# Canonical pattern (``feature/<task-ref>``) plus each documented
+# exception lives here as a single tuple of ``BranchGrammarEntry``
+# rows. Consumers (``check_branch_naming``, lifecycle resolver mirror,
+# bootstrap pre-commit gate) read from this registry instead of
+# hand-rolling exception lists.
+
+
+@dataclass(frozen=True)
+class BranchGrammarEntry:
+    kind: str
+    regex: re.Pattern[str]
+    allowed_in: frozenset[str] = field(default_factory=frozenset)
+
+
+@dataclass(frozen=True)
+class BranWORKSTATElassification:
+    kind: str
+    branch: str
+
+
+_RELEASE_RE = re.compile(r"^release/\d+(\.\d+){1,2}(?:-[a-z0-9]+)?$")
+_HOTFIX_RE = re.compile(r"^hotfix/[a-z][a-z0-9-]*$")
+_MAINT_RE = re.compile(r"^maint/[a-z][a-z0-9-]*$")
+_REVERT_RE = re.compile(r"^revert/[a-z][a-z0-9-]*$")
+_MAIN_RE = re.compile(r"^(main|master)$")
+
+_ALL_MODES: frozenset[str] = frozenset({"post_checkout_warn", "pretooluse", "pre_commit", "pre_push"})
+
+BRANCH_GRAMMAR_REGISTRY: tuple[BranchGrammarEntry, ...] = (
+    BranchGrammarEntry(kind="feature", regex=TASK_REF_RE, allowed_in=_ALL_MODES),
+    BranchGrammarEntry(kind="release", regex=_RELEASE_RE, allowed_in=_ALL_MODES),
+    BranchGrammarEntry(kind="hotfix", regex=_HOTFIX_RE, allowed_in=_ALL_MODES),
+    BranchGrammarEntry(kind="maint", regex=_MAINT_RE, allowed_in=_ALL_MODES),
+    BranchGrammarEntry(kind="revert", regex=_REVERT_RE, allowed_in=_ALL_MODES),
+    BranchGrammarEntry(kind="main", regex=_MAIN_RE, allowed_in=_ALL_MODES),
+)
+
+
+def classify_branch(name: str) -> BranWORKSTATElassification | None:
+    """Return the :class:`BranWORKSTATElassification` for ``name`` or ``None``.
+
+    Unknown patterns return ``None`` (fail-closed); each consumer
+    decides whether unknown means warn or block.
+    """
+
+    for entry in BRANCH_GRAMMAR_REGISTRY:
+        if entry.regex.match(name):
+            return BranWORKSTATElassification(kind=entry.kind, branch=name)
+    return None
+
+
+def is_allowed_branch(name: str, *, mode: str) -> bool:
+    """Return ``True`` when ``name`` matches a registered pattern allowed in ``mode``.
+
+    ``mode`` is a free-form selector — consumers pass their gate name
+    (``post_checkout_warn``, ``pretooluse``, ``pre_commit``,
+    ``pre_push``) and the registry's per-entry ``allowed_in`` set
+    decides whether to admit it.
+    """
+
+    for entry in BRANCH_GRAMMAR_REGISTRY:
+        if entry.regex.match(name) and mode in entry.allowed_in:
+            return True
+    return False

workstate_protocol/compaction.py

@@ -0,0 +1,68 @@
+"""Compaction contract schemas for cross-harness session summaries."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from .handoff import TaskRef
+
+
+class DecisionRef(BaseModel):
+    """Stable decision pointer captured in a compaction summary."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    decision_id: str = Field(description="Stable decision identifier recorded in handoff.")
+    slug: str = Field(description="Human-readable decision slug used for quick inspection.")
+
+
+class TurnRange(BaseModel):
+    """Inclusive turn range covered by the compaction summary."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    start_turn: int = Field(ge=1, description="Inclusive 1-indexed first turn covered by the summary.")
+    end_turn: int = Field(ge=1, description="Inclusive 1-indexed last turn covered by the summary.")
+
+    @model_validator(mode="after")
+    def _validate_bounds(self) -> "TurnRange":
+        if self.end_turn < self.start_turn:
+            raise ValueError("end_turn must be greater than or equal to start_turn")
+        return self
+
+
+class StructuredSummary(BaseModel):
+    """Durable structured summary stored for cross-harness compaction."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    compaction_id: str = Field(description="Server-generated stable compaction handle.")
+    session_id: str = Field(description="Harness session identifier for the compacted transcript span.")
+    harness: Literal["claude-code", "codex", "vscode", "manual"] = Field(
+        description="Harness that produced the compaction record."
+    )
+    task_ref: TaskRef
+    turn_range: TurnRange
+    decisions: list[DecisionRef] = Field(default_factory=list)
+    findings_fixed: list[str] = Field(default_factory=list)
+    findings_opened: list[str] = Field(default_factory=list)
+    tests_verified: list[str] = Field(default_factory=list)
+    files_touched: list[str] = Field(default_factory=list)
+    prose_residual: str | None = Field(
+        default=None,
+        description="Narrative spans that the extractor could not resolve to structured IDs.",
+    )
+    created_at: datetime = Field(description="Timestamp when the compaction row was created.")
+
+    @field_validator("harness", mode="before")
+    @classmethod
+    def _normalize_harness(cls, value: object) -> object:
+        if not isinstance(value, str):
+            return value
+        normalized = value.strip().lower()
+        if normalized == "cursor":
+            return "vscode"
+        return normalized

workstate_protocol/env_aliases.py

@@ -0,0 +1,97 @@
+"""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/handoff.py

@@ -0,0 +1,220 @@
+"""Handoff state schemas (Schema #1 from founding implementation note).
+
+These are the cross-repo contract types for handoff state. They model
+the wire shape that ``mcp-workstate-handoff`` exposes to MCP clients and
+that ``mcp-workstate-orchestrator`` consumes — not the on-disk SQLite row
+shape, which is an implementation detail.
+
+Compatibility note: ``ActiveTask`` is permissive on extra keys
+(``extra='allow'``) because the underlying handoff DB row carries
+columns that this schema does not yet model (revision metadata, lane
+metadata, etc.). As subsequent schema slices land, those fields
+graduate from passthrough to typed.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints
+
+# ---------------------------------------------------------------------------
+# Primitive identifiers and enums
+# ---------------------------------------------------------------------------
+
+# A task_ref is a short identifier like "WORKSTATE-REF-17-14" or "WORKSTATE-REF-7" or "AAA-1".
+# We require non-empty string with a permissive character class so domain
+# tools can introduce new prefixes without re-releasing the protocol.
+TaskRef = Annotated[
+    str,
+    StringConstraints(strip_whitespace=True, min_length=1, max_length=128),
+    Field(description="Short task identifier, e.g. 'WORKSTATE-REF-17-14' or 'WORKSTATE-REF-7'."),
+]
+
+
+class HandoffStatus(str, Enum):
+    """Lifecycle status of a handoff row.
+
+    Mirrors the CHECK constraint on ``handoff_state.status`` in
+    ``mcp-workstate-handoff`` (``shared_schema.py``).
+    """
+
+    in_progress = "in_progress"
+    blocked = "blocked"
+    review = "review"
+    done = "done"
+
+
+class TaskPlanResolution(str, Enum):
+    """How an absolute task-plan path was resolved at read time.
+
+    ``absolute``: the configured ``task_plan_path`` was already absolute.
+    ``worktree``: resolved against ``target_worktree_path``.
+    ``workspace``: resolved against the configured workspace root because
+                   no ``target_worktree_path`` was set.
+    ``unresolved``: resolution failed (no worktree, no workspace).
+    """
+
+    absolute = "absolute"
+    worktree = "worktree"
+    workspace = "workspace"
+    unresolved = "unresolved"
+
+
+# ---------------------------------------------------------------------------
+# Composite models
+# ---------------------------------------------------------------------------
+
+
+class TargetWorktree(BaseModel):
+    """The branch + filesystem location where a task's work lives."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    target_branch: str | None = Field(
+        default=None,
+        description="Git branch the task targets (e.g. 'feature/e17-14').",
+    )
+    target_worktree_path: str | None = Field(
+        default=None,
+        description="Absolute path to the worktree where the task's branch is checked out.",
+    )
+
+
+class TaskPlanRef(BaseModel):
+    """Structured pointer to a task's planning artifact.
+
+    Replaces inferring plan paths from the freeform ``focus`` field.
+    The triple (path, abs_path, exists, resolution) is computed by the
+    handoff runtime against ``target_worktree_path`` and surfaced on
+    every active row so the root workspace can discover and open plans
+    living in sibling worktrees without switching the root checkout.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    task_plan_path: str = Field(
+        description="Repo-relative path (or absolute path) to the planning artifact."
+    )
+    task_plan_abs_path: str | None = Field(
+        default=None,
+        description="Absolute path resolved against the target worktree.",
+    )
+    task_plan_exists: bool | None = Field(
+        default=None,
+        description="Whether the resolved absolute path is a regular file at read time.",
+    )
+    task_plan_resolution: TaskPlanResolution | None = Field(
+        default=None,
+        description="How task_plan_abs_path was derived.",
+    )
+
+
+class ActiveTask(BaseModel):
+    """Wire shape for a single active handoff row.
+
+    Carries identifiers, status, optional target worktree, optional
+    structured task-plan reference, and a revision counter used for
+    optimistic concurrency control. ``extra='allow'`` lets older or
+    newer columns (lane metadata, audit fields) round-trip without
+    requiring a coordinated bump of every consumer.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    task_ref: TaskRef
+    objective: str = Field(description="Human-readable task objective.")
+    focus: str | None = Field(
+        default=None,
+        description="Freeform context for the current iteration. Not a plan-path source — see task_plan_path.",
+    )
+    status: HandoffStatus = HandoffStatus.in_progress
+    revision: int = Field(default=0, ge=0, description="Optimistic-concurrency counter.")
+
+    target_branch: str | None = None
+    target_worktree_path: str | None = None
+
+    # Flat task-plan fields rather than a nested object: matches the wire
+    # shape produced by _enrich_handoff_active in the handoff runtime,
+    # so existing dict consumers don't have to change keys.
+    task_plan_path: str | None = None
+    task_plan_abs_path: str | None = None
+    task_plan_exists: bool | None = None
+    task_plan_resolution: TaskPlanResolution | None = None
+
+    def target_worktree(self) -> TargetWorktree:
+        return TargetWorktree(
+            target_branch=self.target_branch,
+            target_worktree_path=self.target_worktree_path,
+        )
+
+    def task_plan(self) -> TaskPlanRef | None:
+        if self.task_plan_path is None:
+            return None
+        return TaskPlanRef(
+            task_plan_path=self.task_plan_path,
+            task_plan_abs_path=self.task_plan_abs_path,
+            task_plan_exists=self.task_plan_exists,
+            task_plan_resolution=self.task_plan_resolution,
+        )
+
+
+class HandoffState(BaseModel):
+    """Top-level handoff state surface.
+
+    A list of active tasks plus a pointer to which one resolves to the
+    current workspace context (``active_task_ref``). The single-active
+    fallback (``active``) is kept for callers that still expect the
+    legacy single-task envelope; it equals the entry whose ``task_ref``
+    matches ``active_task_ref`` when present.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    active_tasks: list[ActiveTask] = Field(default_factory=list)
+    active_task_ref: TaskRef | None = None
+    active: ActiveTask | None = None
+
+    @classmethod
+    def from_identity_envelope(cls, envelope: dict) -> "HandoffState":
+        """Adapter from the legacy ``get_handoff_state`` MCP envelope.
+
+        Accepts the shape ``{"ok": True, "tool": ..., "task_ref": ...,
+        "data": {"active": {...}, ...}}`` and reshapes it to a
+        single-active ``HandoffState``. Multi-active variants will be
+        added when the runtime exposes them.
+
+        Identity consistency: when both the outer ``envelope['task_ref']``
+        and the inner ``data.active.task_ref`` are present and differ,
+        this raises ``ValueError`` rather than silently picking one.
+        That prevents the adapter from constructing a logically
+        inconsistent ``HandoffState`` whose ``active_task_ref`` does
+        not point at the only active task.
+
+        Use this in tests and consumer-side validation where you have
+        an envelope and want to enforce the cross-repo top-level shape
+        without reshaping the runtime first.
+        """
+        if not isinstance(envelope, dict):
+            raise TypeError(f"envelope must be a dict, got {type(envelope).__name__}")
+        data = envelope.get("data") or {}
+        if not isinstance(data, dict):
+            raise TypeError("envelope['data'] must be a dict")
+        active_raw = data.get("active")
+        active = ActiveTask.model_validate(active_raw) if isinstance(active_raw, dict) else None
+
+        outer_ref = envelope.get("task_ref")
+        inner_ref = active.task_ref if active is not None else None
+        if outer_ref and inner_ref and outer_ref != inner_ref:
+            raise ValueError(
+                f"envelope identity mismatch: envelope['task_ref']={outer_ref!r} "
+                f"but data.active.task_ref={inner_ref!r}. The handoff envelope "
+                "must be self-consistent before adapting to HandoffState."
+            )
+        active_task_ref = inner_ref or outer_ref
+        return cls(
+            active=active,
+            active_task_ref=active_task_ref,
+            active_tasks=[active] if active is not None else [],
+        )

workstate_protocol/hooks.py

@@ -0,0 +1,100 @@
+"""Hook event payload schemas (Schema #3 from founding implementation note).
+
+Models the JSON Claude Code delivers to hook scripts on stdin. Each
+event type is modeled separately rather than as a discriminated union
+so individual hook scripts can validate against the precise event they
+expect without parsing every variant.
+
+``extra='allow'`` everywhere because Claude Code may add fields in
+future releases and we don't want hooks to break on benign additions —
+the contract guarantees the named fields, not exhaustive coverage.
+
+Tag scheme: ``hook_event_name`` matches the literal string Claude Code
+emits, so a hook script can do:
+
+    raw = json.loads(sys.stdin.read())
+    match raw["hook_event_name"]:
+        case "PreToolUse":
+            event = PreToolUseEvent.model_validate(raw)
+        case ...
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _HookEventBase(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    session_id: str = Field(description="Stable per-session identifier from Claude Code.")
+    transcript_path: str | None = Field(
+        default=None,
+        description="Filesystem path to the active session transcript, when emitted by the harness.",
+    )
+    cwd: str | None = Field(
+        default=None,
+        description="Working directory of the Claude Code process at event time.",
+    )
+
+
+class SessionStartEvent(_HookEventBase):
+    hook_event_name: Literal["SessionStart"] = "SessionStart"
+    source: str | None = Field(
+        default=None,
+        description="Why the session started (e.g. 'startup', 'resume', 'compact').",
+    )
+
+
+class UserPromptSubmitEvent(_HookEventBase):
+    hook_event_name: Literal["UserPromptSubmit"] = "UserPromptSubmit"
+    prompt: str = Field(description="Raw text of the user's submitted prompt.")
+
+
+class PreToolUseEvent(_HookEventBase):
+    hook_event_name: Literal["PreToolUse"] = "PreToolUse"
+    tool_name: str = Field(description="Tool the model is about to invoke.")
+    tool_input: dict[str, Any] = Field(default_factory=dict, description="Arguments the model passed to the tool.")
+
+
+class PostToolUseEvent(_HookEventBase):
+    hook_event_name: Literal["PostToolUse"] = "PostToolUse"
+    tool_name: str
+    tool_input: dict[str, Any] = Field(default_factory=dict)
+    tool_response: Any | None = Field(
+        default=None,
+        description="Tool result (shape varies by tool; passthrough so hooks can inspect freely).",
+    )
+
+
+class StopEvent(_HookEventBase):
+    hook_event_name: Literal["Stop"] = "Stop"
+    stop_hook_active: bool | None = Field(
+        default=None,
+        description="True when a previous Stop hook already ran for this turn.",
+    )
+
+
+_EVENT_TYPES: dict[str, type[_HookEventBase]] = {
+    "SessionStart": SessionStartEvent,
+    "UserPromptSubmit": UserPromptSubmitEvent,
+    "PreToolUse": PreToolUseEvent,
+    "PostToolUse": PostToolUseEvent,
+    "Stop": StopEvent,
+}
+
+
+def parse_hook_event(payload: dict[str, Any]) -> _HookEventBase:
+    """Validate ``payload`` against the matching hook-event schema.
+
+    Hook scripts call this on the dict they get from
+    ``json.loads(sys.stdin.read())`` to enforce the wire contract at
+    the entrypoint. Raises ``ValueError`` for unknown event names and
+    re-raises ``pydantic.ValidationError`` for shape failures.
+    """
+    name = payload.get("hook_event_name")
+    if name not in _EVENT_TYPES:
+        raise ValueError(f"unknown hook_event_name: {name!r}")
+    return _EVENT_TYPES[name].model_validate(payload)

workstate_protocol/skills.py

@@ -0,0 +1,61 @@
+"""Skill manifest schema (Schema #4 from founding implementation note).
+
+Structured contract for the canonical neutral skill layout
+``skills/<slug>/skill.yaml`` (implementation note step 1). The pre-Plan-0002
+``.claude/skills/<slug>/SKILL.md`` frontmatter is now a *generated*
+artifact in target repos and is no longer a source-of-truth surface.
+Enforces the Tier 1 / Tier 2 / Tier 3 portability boundary by
+requiring an explicit ``scope`` declaration on every skill —
+preventing project-specific skills from being accidentally hoisted
+into the harness overlay.
+
+``extra='allow'`` so existing harness fields (``mode``, ``context_budget``,
+``mcp_tools``, ``tdd_gate``, ``makefile_target``, etc.) round-trip
+unchanged. The schema only enforces the cross-repo portability
+contract; consumer-specific validators continue to enforce their own
+fields locally.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SkillScope(str, Enum):
+    """Portability scope of a skill.
+
+    ``harness``: project-agnostic. Lives in ``workstate-system`` source of
+                 truth and is installed/symlinked into target repos by
+                 ``workstate-bootstrap``. Must not reference project-specific
+                 paths, package names, or domain terminology.
+    ``project``: project-specific. Stays in the target repo's
+                 ``skills/`` (or its generated ``.claude/skills/``
+                 mirror) and is never hoisted by bootstrap. May freely
+                 reference project-local apps, packages, and
+                 conventions.
+    """
+
+    harness = "harness"
+    project = "project"
+
+
+class SkillManifest(BaseModel):
+    """Required cross-repo fields on a skill's frontmatter."""
+
+    model_config = ConfigDict(extra="allow")
+
+    name: str = Field(min_length=1, description="Unique skill identifier (kebab-case).")
+    description: str = Field(min_length=1, description="One-line description used for skill matching.")
+    scope: SkillScope = Field(
+        description="Portability scope. 'harness' = installed into target repos by bootstrap; 'project' = stays local.",
+    )
+    triggers: list[str] | None = Field(
+        default=None,
+        description="Optional list of trigger phrases or patterns the skill responds to.",
+    )
+    model: str | None = Field(
+        default=None,
+        description="Optional preferred model identifier (e.g. 'claude-opus-4-7').",
+    )

workstate_protocol-0.1.5.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: workstate-protocol
+Version: 0.1.5
+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
+Project-URL: Source, https://github.com/darce/workstate/tree/main/packages/workstate-protocol
+Project-URL: Changelog, https://github.com/darce/workstate/blob/main/packages/workstate-protocol/CHANGELOG.md
+Project-URL: Issues, https://github.com/darce/workstate/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# workstate-protocol
+
+Single source of truth for cross-repo contracts in the Workstate system. Pydantic v2 is canonical; JSON Schema artifacts under `schemas/` are generated from the models so non-Python consumers (hook scripts, future TS/JS tooling) can validate without importing Python.
+
+## Schemas (rolled out incrementally per founding implementation note)
+
+| Status | Module | Schema |
+| --- | --- | --- |
+| ✅ v0.1.0 | `workstate_protocol.handoff` | `HandoffState`, `ActiveTask`, `TaskRef`, `TargetWorktree`, `TaskPlanRef` |
+| ✅ v0.1.0 | `workstate_protocol.branch_naming` | `TASK_REF_RE`, `derive_task_ref_candidates`, `format_suggested_branch_name` (single source of truth for the feature-branch grammar enforced by the post-checkout / PreToolUse / pre-commit / pre-push gates; cross-package consumers like `workstate_handoff_mcp` re-export by reference, never by literal copy — identity is the contract) |
+| ⏳ | `workstate_protocol.mcp` | MCP tool I/O envelopes |
+| ⏳ | `workstate_protocol.hooks` | `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop` |
+| ⏳ | `workstate_protocol.skills` | `SkillManifest` (with `scope: harness | project`) |
+| ⏳ | `workstate_protocol.bootstrap` | Bootstrap install manifest |
+
+## Generated artifacts
+
+`schemas/*.json` is regenerated by `scripts/generate_schemas.py` and committed. Consumers that don't want to import Python can read the JSON Schema directly.
+
+## Versioning
+
+Hard-pin major version per consumer. Bootstrap resolves a compatible quartet of (handoff, orchestrator, bootstrap, system) against a single `workstate-protocol` major.

workstate_protocol-0.1.5.dist-info/RECORD

@@ -0,0 +1,13 @@
+workstate_protocol/__init__.py,sha256=Arjsuu4xlUxi2QFRhHN78k3-CmCo1eudcJJVgTiXXO8,1653
+workstate_protocol/bootstrap.py,sha256=HIvNaFSbGV4fQlw8tqGWT44sD6KtmegNyBekU7Wtw-4,8857
+workstate_protocol/branch_naming.py,sha256=31sa-AWtlEANq8Ay_zA4jnm9PMTHUYc9fV4ip49giYk,8479
+workstate_protocol/compaction.py,sha256=4suCZW1RLCuJSZNIn08N1lhvQB81LvCMyu98oahLaPc,2623
+workstate_protocol/env_aliases.py,sha256=NqjOnWS4EE_vcSiEx_wOmTrd8dhcnK3FsFMmGnb5erg,3132
+workstate_protocol/handoff.py,sha256=DyOX7pmOoo3v8RFsCVLFEvkgFqz_2QLWzJad0DYO9o8,8598
+workstate_protocol/hooks.py,sha256=zrs9FKT4nuMCkd8feHnI4OYYSFYuDAadMVZJNYSTmNo,3566
+workstate_protocol/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+workstate_protocol/skills.py,sha256=Q8zhjdr5Bphp9H3YcmzhQ8qXUtgoiezWxLqbhoVK-6M,2471
+workstate_protocol-0.1.5.dist-info/METADATA,sha256=JyOo5bgjk4T73xnz0oTYkHGbrEwGTiaJ-OShOMPZ5ZM,2318
+workstate_protocol-0.1.5.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+workstate_protocol-0.1.5.dist-info/top_level.txt,sha256=0g332GBrFdObOsFWiWcgKOgdizfwrDZYzTk4FfQRwKk,19
+workstate_protocol-0.1.5.dist-info/RECORD,,

workstate_protocol-0.1.5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

workstate_protocol-0.1.5.dist-info/top_level.txt

@@ -0,0 +1 @@
+workstate_protocol