mokata 0.0.9__py3-none-any.whl

mokata/__init__.py

@@ -0,0 +1,72 @@
+# mokata — framework spine.
+#
+# Copyright 2026 MoStack. Licensed under the Apache License, Version 2.0.
+#
+# The spine is the conductor every other layer plugs into:
+#   - A1 stack manifest (schema + file)          -> manifest.py, schema.py
+#   - A2 capability router (need -> tool + fallback) -> router.py
+#   - A3 tool-presence detection + degradation    -> detect.py
+#   - A4 SessionStart bootstrap (<= 2k tokens)     -> bootstrap.py
+#   - A5 unified config + constitution surface     -> config.py
+#   - A7 `mokata init` onboarding                  -> init.py, profiles.py, cli.py
+
+__version__ = "0.0.9"
+
+# The directory, relative to a repo root, that holds mokata's committed config.
+MOKATA_DIR = ".mokata"
+MANIFEST_FILENAME = "manifest.json"
+CONSTITUTION_FILENAME = "constitution.md"
+
+# Everything mokata creates as its own data lives under MOKATA_DIR. Inside it there is a
+# committed/transient split (Stage 24D): committed config (manifest, constitution, an
+# exported stack if the team commits it) sits at the .mokata/ root; everything
+# transient/runtime (pipeline state, resume checkpoints, the freshness index, caches, the
+# SQLite memory store + vault, and — by default — the audit ledger) lives under
+# .mokata/temp_local/, which a committed .mokata/.gitignore keeps out of version control.
+TEMP_LOCAL_DIRNAME = "temp_local"
+
+
+def package_data_root():
+    """The directory that holds mokata's packaged data — ``templates/``, ``hooks/``,
+    ``skills/`` (and ``stacks/``).
+
+    Stage 3 relocated that data INSIDE the installed package (``src/mokata/…``), so it
+    resolves the SAME way for a pip-installed wheel and for an editable/clone install:
+    ``importlib.resources.files("mokata")`` is the package directory in both cases (site-
+    packages for a wheel, ``<clone>/src/mokata`` for ``-e .``). This removes the old
+    ``parents[2]`` clone assumption that made ``pip install <wheel>`` unable to run
+    ``mokata setup``. Falls back to this module's own directory if importlib.resources
+    can't hand back a concrete filesystem path (never raises)."""
+    from pathlib import Path
+    try:
+        from importlib.resources import files
+        root = Path(str(files("mokata")))
+        if root.is_dir():
+            return root
+    except Exception:
+        pass
+    return Path(__file__).resolve().parent
+
+
+def _force_utf8_io() -> None:
+    """On Windows, make stdout/stderr speak UTF-8 so mokata's console output — arrows (→),
+    checkmarks (✓), box drawing, em-dashes — never dies with `UnicodeEncodeError` on the legacy
+    cp1252 console (or a cp1252 pipe when output is captured). POSIX terminals are already UTF-8,
+    so this is a no-op there, keeping behavior byte-identical across platforms. Fully guarded:
+    it never raises and never blocks import (an embedder with an exotic stream is left alone)."""
+    import os
+    import sys
+
+    if os.name != "nt":
+        return
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            reconfigure = getattr(stream, "reconfigure", None)
+            current = (getattr(stream, "encoding", "") or "").lower().replace("-", "")
+            if reconfigure is not None and current != "utf8":
+                reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+
+
+_force_utf8_io()

mokata/__main__.py

@@ -0,0 +1,6 @@
+"""Enables `python -m mokata ...` (no install required)."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mokata/adapters/__init__.py

@@ -0,0 +1,39 @@
+"""mokata adapter & negotiation layer (Part A6 / H4–H6).
+
+A typed adapter ecosystem mokata can reason about, built on the Stage-1 capability model:
+  - A6: AdapterContract + negotiate -> coverage and unmet gaps.
+  - H5: validate_adapter -> validate a third-party adapter against the contract.
+  - H4: MCPRegistry / discover_mcp_servers -> enumerate MCP servers, map to roles
+        (degrades cleanly when none present).
+  - H6: declared_precedence / overlapping_capabilities / resolve_conflict -> two tools
+        claiming one role are resolved by manifest precedence; the router honors it.
+"""
+
+from .contract import (
+    AdapterContract,
+    CoverageReport,
+    negotiate,
+    validate_adapter,
+)
+from .mcp import MCPRegistry, MCPServer, discover_mcp_servers
+from .precedence import (
+    declared_precedence,
+    overlapping_capabilities,
+    resolve_conflict,
+)
+
+__all__ = [
+    # A6 / H5
+    "AdapterContract",
+    "CoverageReport",
+    "negotiate",
+    "validate_adapter",
+    # H4
+    "MCPServer",
+    "MCPRegistry",
+    "discover_mcp_servers",
+    # H6
+    "declared_precedence",
+    "overlapping_capabilities",
+    "resolve_conflict",
+]

mokata/adapters/contract.py

@@ -0,0 +1,97 @@
+"""A6 + H5 — typed adapter contract.
+
+A6: an `AdapterContract` declares which capabilities a tool provides, so `negotiate`
+can report coverage and the unmet gaps across a set of needs. H5: `validate_adapter`
+checks a third party's adapter dict against the contract before it is wired in. Reuses
+the spine's capability vocabulary (schema kinds/detect types) — one capability model.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from ..schema import KNOWN_DETECT_TYPES, KNOWN_TOOL_KINDS
+
+
+@dataclass
+class AdapterContract:
+    name: str
+    provides: List[str]
+    kind: str = "external"
+    version: Optional[str] = None
+    detect: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {"name": self.name, "provides": list(self.provides),
+                             "kind": self.kind, "version": self.version}
+        if self.detect is not None:
+            d["detect"] = dict(self.detect)
+        return d
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "AdapterContract":
+        return cls(name=data["name"], provides=list(data.get("provides", [])),
+                   kind=data.get("kind", "external"), version=data.get("version"),
+                   detect=data.get("detect"))
+
+
+def validate_adapter(data: Any) -> List[str]:
+    """Return contract-violation errors for a candidate adapter (empty == valid)."""
+    errors: List[str] = []
+    if not isinstance(data, dict):
+        return ["adapter must be an object"]
+    if not isinstance(data.get("name"), str) or not data.get("name"):
+        errors.append("adapter.name must be a non-empty string")
+    provides = data.get("provides")
+    if not isinstance(provides, list) or not provides:
+        errors.append("adapter.provides must be a non-empty array")
+    else:
+        for p in provides:
+            if not isinstance(p, str) or not p:
+                errors.append("adapter.provides entries must be non-empty strings")
+                break
+    kind = data.get("kind", "external")
+    if kind not in KNOWN_TOOL_KINDS:
+        errors.append(f"adapter.kind '{kind}' invalid (one of {KNOWN_TOOL_KINDS})")
+    detect = data.get("detect")
+    if detect is not None:
+        if not isinstance(detect, dict):
+            errors.append("adapter.detect must be an object")
+        else:
+            dt = detect.get("type")
+            if dt not in KNOWN_DETECT_TYPES:
+                errors.append(f"adapter.detect.type '{dt}' invalid")
+            elif dt in ("command", "python_module", "path") and not detect.get("name"):
+                errors.append(f"adapter.detect.name is required for type '{dt}'")
+    return errors
+
+
+@dataclass
+class CoverageReport:
+    needs: List[str]
+    covered: Dict[str, List[str]] = field(default_factory=dict)
+    gaps: List[str] = field(default_factory=list)
+
+    @property
+    def fully_covered(self) -> bool:
+        return not self.gaps
+
+    def render(self) -> str:
+        lines = ["capability coverage:"]
+        for need in self.needs:
+            who = self.covered.get(need) or []
+            mark = ", ".join(who) if who else "— UNMET"
+            lines.append(f"  {need}: {mark}")
+        if self.gaps:
+            lines.append(f"gaps: {', '.join(self.gaps)}")
+        else:
+            lines.append("gaps: none — full coverage")
+        return "\n".join(lines)
+
+
+def negotiate(needs: List[str], adapters: List[AdapterContract]) -> CoverageReport:
+    """Report which needs each adapter set covers, and which remain unmet (A6)."""
+    covered = {need: [a.name for a in adapters if need in a.provides] for need in needs}
+    gaps = [need for need in needs if not covered[need]]
+    return CoverageReport(needs=list(needs), covered=covered, gaps=gaps)

mokata/adapters/mcp.py

@@ -0,0 +1,85 @@
+"""H4 — MCP registry + discovery.
+
+Enumerate available MCP servers (from an injected config or a JSON file) and map them to
+stack roles (capabilities) via the capabilities they declare. Discovery is pluggable and
+degrades cleanly: with no config/file present, the registry is empty and never errors.
+Each MCP server is also an `AdapterContract`, so it flows into A6 negotiation.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from .contract import AdapterContract
+
+
+@dataclass
+class MCPServer:
+    name: str
+    provides: List[str] = field(default_factory=list)
+    command: Optional[str] = None
+    url: Optional[str] = None
+
+    def to_adapter(self) -> AdapterContract:
+        return AdapterContract(name=self.name, provides=list(self.provides), kind="mcp")
+
+
+def _normalize(entries: Any) -> List[MCPServer]:
+    servers: List[MCPServer] = []
+    if isinstance(entries, dict):
+        # { name: {provides, command, url} } form
+        items = [{"name": k, **(v or {})} for k, v in entries.items()]
+    elif isinstance(entries, list):
+        items = entries
+    else:
+        return []
+    for e in items:
+        if not isinstance(e, dict) or not e.get("name"):
+            continue
+        servers.append(MCPServer(name=e["name"], provides=list(e.get("provides", [])),
+                                 command=e.get("command"), url=e.get("url")))
+    return servers
+
+
+def discover_mcp_servers(config: Any = None,
+                         path: Optional[str] = None) -> List[MCPServer]:
+    """Discover MCP servers from an injected config, a JSON file, or — failing both —
+    return [] (degrade cleanly; no MCP present)."""
+    if config is not None:
+        return _normalize(config)
+    if path and os.path.exists(path):
+        try:
+            with open(path, encoding="utf-8") as fh:
+                return _normalize(json.load(fh))
+        except (OSError, ValueError):
+            return []
+    return []
+
+
+class MCPRegistry:
+    def __init__(self, servers: List[MCPServer]) -> None:
+        self.servers = servers
+
+    @classmethod
+    def discover(cls, config: Any = None,
+                 path: Optional[str] = None) -> "MCPRegistry":
+        return cls(discover_mcp_servers(config=config, path=path))
+
+    def names(self) -> List[str]:
+        return [s.name for s in self.servers]
+
+    def map_to_roles(self) -> Dict[str, List[str]]:
+        roles: Dict[str, List[str]] = {}
+        for s in self.servers:
+            for cap in s.provides:
+                roles.setdefault(cap, []).append(s.name)
+        return roles
+
+    def servers_for(self, capability: str) -> List[MCPServer]:
+        return [s for s in self.servers if capability in s.provides]
+
+    def adapters(self) -> List[AdapterContract]:
+        return [s.to_adapter() for s in self.servers]

mokata/adapters/precedence.py

@@ -0,0 +1,36 @@
+"""H6 — conflict / overlap resolution.
+
+When two tools claim the same role, the manifest's declared precedence (the capability's
+fallback order, A2) resolves it. This surfaces overlaps and the precedence; the existing
+router already honors it deterministically (it walks the fallback order and picks the
+first present provider) — there is no parallel resolution path.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Set
+
+
+def declared_precedence(manifest: Any, need: str) -> List[str]:
+    """The precedence order for a capability — i.e. its declared fallback order."""
+    return manifest.fallback_order(need)        # raises ManifestError if unknown
+
+
+def overlapping_capabilities(manifest: Any) -> Dict[str, List[str]]:
+    """Capabilities claimed by more than one provider (an overlap to be resolved by
+    precedence)."""
+    out: Dict[str, List[str]] = {}
+    for need in manifest.capabilities:
+        order = manifest.fallback_order(need)
+        if len(order) > 1:
+            out[need] = order
+    return out
+
+
+def resolve_conflict(manifest: Any, need: str,
+                     present: Set[str]) -> Optional[str]:
+    """The winning provider for a need: the highest-precedence one that is present."""
+    for tool in declared_precedence(manifest, need):
+        if tool in present:
+            return tool
+    return None

mokata/agent_skills.py

@@ -0,0 +1,251 @@
+"""Agent Skills surface — the model-invocable twin of mokata's slash commands.
+
+Claude Code exposes TWO distinct surfaces: slash *commands* (`/mokata:<name>`) and *Agent
+Skills* (`SKILL.md` files Claude auto-engages from their `description`). mokata already ships
+commands; this module renders the matching Agent Skills so mokata's capabilities also appear
+in — and auto-trigger from — the Agent Skills list.
+
+Single source, no drift: a skill is rendered from the SAME `templates/commands/<name>.md`
+template the command ships from. The skill's trigger text is the template's own
+`description` (+ `when_to_use` when present); the skill's body is the template's protocol
+body VERBATIM, behind a fixed banner. Nothing is hand-copied, so the two surfaces can't
+diverge — a drift-guard test re-renders and compares, exactly like the command templates.
+
+Curated: only capabilities a user would want Claude to engage on its own are surfaced (the
+pipeline gates + knowledge/session capabilities) — not the pure utilities (version, tour,
+setup, …). The allow-list is an explicit constant below; add/remove a name to tune it.
+
+Precedence note (Claude Code): when a skill and a command share a name, the SKILL takes
+precedence. That's why the body carries the full protocol inline and never tells Claude to
+"go run the /<name> command" (which would loop) — it follows the protocol right here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+# The curated allow-list: command names that are genuinely MODEL-INVOCABLE — Claude should be
+# able to engage them on its own when the moment fits. Pipeline gates + knowledge/session
+# capabilities. Deliberately EXCLUDES pure utilities/orchestration mechanics (version, tour,
+# setup, reconfigure, upgrade, init, enter, exec, resume, watch, progress, chain, decompose,
+# skill, stacks, team, vault). Keep alphabetical-by-intent groups for legibility.
+CURATED_SKILLS: tuple = (
+    # exploration → spec → TDD build → land
+    "brainstorm",
+    "spec",
+    "test",
+    "develop",
+    "review",
+    "refine",
+    "debug",
+    "bug",
+    "optimize",
+    "ship",
+    # knowledge / governance / portability
+    "onboard",
+    "govern",
+    "session",
+    "playbook",
+    # harness repair (Stage 3b.4) — auto-engages when the MCP server/tools aren't connecting
+    "mcp",
+)
+
+# A stable marker every rendered SKILL.md carries (in the banner). unsetup uses it to identify
+# mokata-authored skills for clean removal WITHOUT ever touching a user's own SKILL.md — the
+# same ownership discipline the hook/statusline wiring uses.
+SKILL_MARKER = "mokata Agent Skill."
+
+# The banner every rendered SKILL.md carries above the protocol body. Fixed text (only the
+# capability name is interpolated) so it stays driftless. It frames the skill as the
+# auto-engaged twin of the command and reinforces mokata's human-gate — WITHOUT telling
+# Claude to re-invoke the command (skills shadow commands, so that would loop).
+_SKILL_BANNER = (
+    "> **mokata Agent Skill.** This is mokata's `{name}` capability, surfaced so Claude can "
+    "engage it\n"
+    "> automatically when the moment fits. It runs the SAME protocol as the `/mokata:{name}` "
+    "command,\n"
+    "> from one shared source — follow that protocol directly here; do not hand off to a "
+    "parallel\n"
+    "> flow. mokata's non-negotiables still hold: durable writes are **human-gated** (preview, "
+    "then\n"
+    "> explicit approval), and this capability's own gate is never silently skipped."
+)
+
+
+class SkillSourceError(RuntimeError):
+    """A curated skill's source template is missing or malformed."""
+
+
+@dataclass(frozen=True)
+class SkillSource:
+    name: str
+    description: str
+    when_to_use: Optional[str]
+    body: str                       # the template's protocol body, verbatim (no frontmatter)
+
+
+def parse_frontmatter(md: str) -> Dict[str, str]:
+    """Parse a template's leading `---` frontmatter into a flat dict of single-line values.
+
+    mokata's command templates use simple `key: value` frontmatter (one line per key); this
+    is a deliberately small parser for exactly that shape, not a general YAML loader.
+    """
+    if not md.startswith("---"):
+        return {}
+    end = md.find("\n---", 3)
+    if end == -1:
+        return {}
+    block = md[3:end]
+    fm: Dict[str, str] = {}
+    for line in block.splitlines():
+        if not line.strip() or ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        fm[key.strip()] = value.strip()
+    return fm
+
+
+def _split_frontmatter(md: str) -> str:
+    """Return the body of a template (everything after its `---` frontmatter), leading blank
+    lines stripped. Falls back to the whole text when there is no frontmatter."""
+    if md.startswith("---"):
+        end = md.find("\n---", 3)
+        if end != -1:
+            after = md[end + 4:]           # skip the closing "\n---"
+            nl = after.find("\n")
+            after = after[nl + 1:] if nl != -1 else ""
+            return after.lstrip("\n")
+    return md
+
+
+def load_skill_source(name: str, templates_dir: Path) -> SkillSource:
+    """Read one curated command template and extract the skill source (frontmatter + body)."""
+    path = templates_dir / f"{name}.md"
+    if not path.is_file():
+        raise SkillSourceError(f"no command template for curated skill '{name}' at {path}")
+    md = path.read_text(encoding="utf-8")
+    fm = parse_frontmatter(md)
+    description = fm.get("description", "").strip()
+    if not description:
+        raise SkillSourceError(f"template '{name}.md' has no frontmatter description")
+    when = fm.get("when_to_use") or None
+    return SkillSource(name=name, description=description, when_to_use=when,
+                       body=_split_frontmatter(md))
+
+
+def render_skill_md(src: SkillSource) -> str:
+    """Render a SKILL.md from a skill source. Frontmatter carries the model-invocation trigger
+    (`description` [+ `when_to_use`]); the body is the fixed banner + the command's protocol
+    body verbatim. Deterministic — the drift guard depends on it."""
+    when_line = f"when_to_use: {src.when_to_use}\n" if src.when_to_use else ""
+    return (
+        f"---\n"
+        f"name: {src.name}\n"
+        f"description: {src.description}\n"
+        f"{when_line}"
+        f"---\n\n"
+        f"{_SKILL_BANNER.format(name=src.name)}\n\n"
+        f"{src.body}"
+    )
+
+
+def skill_markdown(name: str, templates_dir: Path) -> str:
+    """One-shot: render the SKILL.md content for a curated skill name from its template."""
+    return render_skill_md(load_skill_source(name, templates_dir))
+
+
+def generate_skill_files(templates_dir: Path,
+                         names: Optional[tuple] = None) -> Dict[str, str]:
+    """Return {name: SKILL.md content} for the curated set (or a supplied subset). This is the
+    single generator both the plugin-root `skills/` tree and the `setup` path render from."""
+    chosen = names if names is not None else CURATED_SKILLS
+    return {name: skill_markdown(name, templates_dir) for name in chosen}
+
+
+def skill_relpaths(names: Optional[tuple] = None) -> List[str]:
+    """The on-disk layout Claude Code expects: `<name>/SKILL.md`, one dir per skill."""
+    chosen = names if names is not None else CURATED_SKILLS
+    return [f"{name}/SKILL.md" for name in chosen]
+
+
+def write_skill_files(skills_dir: Path, files: Dict[str, str]) -> List[Path]:
+    """Materialize {name: content} into `<skills_dir>/<name>/SKILL.md`. Returns written paths."""
+    written: List[Path] = []
+    for name, content in files.items():
+        dst = skills_dir / name / "SKILL.md"
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        dst.write_text(content, encoding="utf-8")
+        written.append(dst)
+    return written
+
+
+def find_orphan_skills(skills_dir: Optional[Path], keep) -> List[Path]:
+    """The mokata-AUTHORED (``SKILL_MARKER``-bearing) ``<skills_dir>/<name>/SKILL.md`` paths whose
+    dir name is NOT in ``keep``. READ-ONLY — this is what the setup PLAN previews and what
+    :func:`prune_orphan_skills` deletes, sharing ONE marker check so plan and apply can't diverge.
+    A skill WITHOUT the marker (a user's own) or an unreadable file is skipped — never flagged."""
+    keep = set(keep)
+    found: List[Path] = []
+    if skills_dir is None:
+        return found
+    d = Path(skills_dir)
+    if not d.is_dir():
+        return found
+    for sk in sorted(d.glob("*/SKILL.md")):
+        if sk.parent.name in keep:
+            continue
+        try:
+            if SKILL_MARKER not in sk.read_text(encoding="utf-8"):
+                continue                         # a user's own skill — never touch it
+        except OSError:
+            continue                             # unreadable → leave it alone, don't crash
+        found.append(sk)
+    return found
+
+
+def prune_orphan_skills(skills_dir: Optional[Path], keep) -> List[Path]:
+    """SYNC the on-disk skills tree to the current curated set: remove every mokata-authored
+    (marker-bearing) skill dir whose name is NOT in ``keep`` — the counterpart to
+    :func:`write_skill_files`, which only writes the current set and never removes a dropped one.
+    Cleans the now-empty ``<name>/`` dir, and the ``skills/`` dir itself if it ends up empty (so
+    ``unsetup``, which passes ``keep=()``, leaves no residue). NEVER removes a non-marker (user)
+    skill; an unreadable/undeletable file is skipped (degrade-clean). Returns the removed paths."""
+    removed: List[Path] = []
+    for sk in find_orphan_skills(skills_dir, keep):
+        try:
+            sk.unlink()
+            removed.append(sk)
+            if not any(sk.parent.iterdir()):
+                sk.parent.rmdir()
+        except OSError:
+            continue                             # can't delete it → leave it, don't crash
+    try:
+        d = Path(skills_dir) if skills_dir is not None else None
+        if d is not None and d.is_dir() and not any(d.iterdir()):
+            d.rmdir()
+    except OSError:
+        pass
+    return removed
+
+
+def _regenerate_plugin_skills() -> List[Path]:
+    """Regenerate the shipped plugin-root `skills/` tree from the command templates. Run this
+    (``python -m mokata.agent_skills``) whenever a curated command's frontmatter changes; the
+    drift-guard test then goes GREEN. This module is the single source — never hand-edit a
+    SKILL.md. It's a SYNC: writes the current curated set, then prunes any marker-bearing skill
+    dir no longer curated, so a removed skill can't ship stale in the wheel/plugin."""
+    from . import package_data_root
+    root = package_data_root()                          # the mokata package dir (holds the data)
+    templates_dir = root / "templates" / "commands"
+    skills_dir = root / "skills"
+    written = write_skill_files(skills_dir, generate_skill_files(templates_dir))
+    prune_orphan_skills(skills_dir, CURATED_SKILLS)     # drop any skill dropped from the curated set
+    return written
+
+
+if __name__ == "__main__":                              # pragma: no cover
+    for _p in _regenerate_plugin_skills():
+        print(_p)

mokata/baseline.py

@@ -0,0 +1,89 @@
+"""Stage 34 Part B — clean-test-baseline check.
+
+Before an implementation run starts, it's worth knowing the test suite is GREEN at baseline,
+so any new failure is attributable to the change (TDD hygiene). This runs the project's
+configured test command and reports green/red. It **degrades cleanly**: when no test command
+is known, it says so and does NOT hard-block (mokata never guesses a test framework — that
+would be an assumption; the user states the command).
+
+The command comes from `settings.baseline.test_command` in the manifest, or an explicit
+override. Running it is a read-only diagnostic the user invokes; it makes no durable write and
+no network call.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from typing import Any, Optional
+
+# settings.baseline.test_command — the project's test command (mokata never guesses one).
+BASELINE_SETTINGS_KEY = "baseline"
+# How long the baseline test command may run before we report (not crash) a timeout.
+BASELINE_TIMEOUT_SECONDS = 600
+
+GREEN = "green"
+RED = "red"
+UNKNOWN = "unknown"
+
+NO_COMMAND_MESSAGE = (
+    "baseline: no test command known — set `settings.baseline.test_command` (or pass one) "
+    "so mokata can confirm a green baseline. Skipping (not a hard failure)."
+)
+
+
+@dataclass
+class BaselineResult:
+    state: str                 # green | red | unknown
+    command: Optional[str] = None
+    detail: str = ""
+    returncode: Optional[int] = None
+
+    @property
+    def ok(self) -> bool:
+        # green is good; unknown degrades clean (not a hard failure); only red is "not ok".
+        return self.state != RED
+
+    def render(self) -> str:
+        if self.state == GREEN:
+            return f"baseline: GREEN — `{self.command}` passed. New failures are yours."
+        if self.state == RED:
+            return (f"baseline: RED — `{self.command}` is already failing (rc "
+                    f"{self.returncode}). Fix or acknowledge before starting, so new "
+                    "failures are attributable to your change.")
+        return NO_COMMAND_MESSAGE
+
+
+def baseline_command(manifest: Any = None, override: Optional[str] = None) -> Optional[str]:
+    """Resolve the test command: an explicit override, else settings.baseline.test_command."""
+    if override:
+        return override
+    if manifest is None:
+        return None
+    try:
+        s = manifest.setting(BASELINE_SETTINGS_KEY, {}) or {}
+    except AttributeError:
+        return None
+    cmd = s.get("test_command") if isinstance(s, dict) else None
+    return cmd or None
+
+
+def baseline_status(command: Optional[str], cwd: Optional[str] = None,
+                    timeout: int = BASELINE_TIMEOUT_SECONDS) -> BaselineResult:
+    """Run the test command and report green/red; UNKNOWN (degrade-clean) when none given.
+    Never raises — a command that can't run reports red with the reason, not an exception."""
+    if not command:
+        return BaselineResult(state=UNKNOWN, detail=NO_COMMAND_MESSAGE)
+    try:
+        # Justification for the B602 suppression: `command` is the USER's OWN test command (their
+        # `settings.baseline` config / CLI arg), run in their own shell exactly as they'd run it;
+        # not attacker-controlled input. A shell is required so a normal test one-liner
+        # (`pytest -q && ruff .`, pipes, globs) works. Bounded by `timeout`; degrade-clean.
+        proc = subprocess.run(command, shell=True, cwd=cwd, capture_output=True,  # nosec B602
+                              text=True, timeout=timeout)
+    except Exception as exc:  # missing binary, timeout, etc. — report, don't crash
+        return BaselineResult(state=RED, command=command,
+                              detail=f"could not run test command: {exc}")
+    state = GREEN if proc.returncode == 0 else RED
+    return BaselineResult(state=state, command=command, returncode=proc.returncode,
+                          detail=(proc.stderr or proc.stdout or "").strip()[-500:])