workstate-protocol 0.1.5__tar.gz

workstate_protocol-0.1.5/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,22 @@
+# 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/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "workstate-protocol"
+version = "0.1.5"
+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"
+license = { text = "MIT" }
+dependencies = [
+    "pydantic>=2.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/darce/workstate"
+Source = "https://github.com/darce/workstate/tree/main/packages/workstate-protocol"
+Changelog = "https://github.com/darce/workstate/blob/main/packages/workstate-protocol/CHANGELOG.md"
+Issues = "https://github.com/darce/workstate/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+workstate_protocol = ["py.typed"]

workstate_protocol-0.1.5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

workstate_protocol-0.1.5/src/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-0.1.5/src/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-0.1.5/src/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