context-guard-cli 2.1.0__py3-none-any.whl

context_guard/guard/transaction.py

@@ -0,0 +1,403 @@
+"""Transaction and checkpoint manager for guard middleware.
+
+Provides state snapshot, rollback, begin, commit, and checkpointing for context-guard sessions.
+Follows the 3-state pipeline model: PLAN -> EXECUTE -> VERIFY -> ARCHIVE.
+"""
+
+from datetime import datetime
+import getpass
+import os
+
+from .paths import get_paths, missing_session_result
+from .manifest import load_manifest, save_manifest, create_initial_manifest
+from .locking import with_write_lock
+from .errors import (
+    CommandResult,
+    EXIT_OK,
+    EXIT_LOCK_HELD,
+    EXIT_GENERIC,
+    EXIT_VALIDATION,
+    EXIT_BAD_TRANSITION,
+    EXIT_APPROVAL_REQUIRED,
+)
+
+DEFAULT_TTL = 1800
+MAX_SUMMARY_CHARS = 2000
+
+VALID_PHASES = ["PLAN", "EXECUTE", "VERIFY"]
+
+TRANSITIONS = {
+    "PLAN": "EXECUTE",
+    "EXECUTE": "VERIFY",
+    "VERIFY": "ARCHIVE",
+}
+
+
+def is_stale(started_at_iso, ttl_seconds):
+    """Verifica si una transacción ha superado su TTL."""
+    if not started_at_iso or started_at_iso == "None":
+        return False
+    try:
+        elapsed = (datetime.now() - datetime.fromisoformat(started_at_iso)).total_seconds()
+        return elapsed > ttl_seconds
+    except (ValueError, TypeError):
+        return False
+
+
+def _scaffold_artifacts(context_path, change=None):
+    """Genera plantillas por defecto en .context-guard/ para la fase PLAN si no existen."""
+    p = get_paths(context_path, change)
+    base_dir = p["base"]
+    os.makedirs(base_dir, exist_ok=True)
+
+    artifacts = {
+        "objective.md": "[PENDING] Define objective here",
+        "snapshot.md": "[PENDING] Define snapshot here",
+        "tasks.md": "[PENDING] Define tasks here",
+        "review-report.md": "[PENDING] Write static review here",
+        "verify-report.md": "[PENDING] Write dynamic verification here",
+    }
+
+    for filename, default_content in artifacts.items():
+        filepath = os.path.join(base_dir, filename)
+        if not os.path.exists(filepath):
+            with open(filepath, "w", encoding="utf-8") as f:
+                f.write(default_content)
+
+
+def _record_approval(m, approval, consumed_as):
+    """Move an approval into the audit trail, spending it.
+
+    An approval left live in the manifest authorizes every future transition
+    into EXECUTE, not just the one the human looked at. Consuming it here is
+    what makes a sign-off single-use.
+    """
+    entry = dict(approval)
+    entry["consumed_at"] = datetime.now().isoformat()
+    entry["consumed_as"] = consumed_as
+    m.setdefault("approval_history", []).append(entry)
+    m.pop("approval", None)
+
+
+def cmd_approve(context, by=None, hotfix=False, reason=None, change=None):
+    """Records the human sign-off that PLAN -> EXECUTE requires.
+
+    This command is cooperative and makes no pretence otherwise: an agent with
+    a shell can run it. What it buys is that the transition cannot happen
+    without *someone* running it, and that whoever did is named in the
+    manifest. The hard control is the harness permission prompt documented in
+    adapters/ — see PLAN.md 0.6.
+
+    `hotfix` is the audited door out of the pipeline: it spends the approval
+    immediately and jumps lock_phase straight to EXECUTE, recording why. It
+    replaces state-guard's parallel bypass flow, whose problem was never that
+    it existed but that nothing survived it.
+    """
+    if hotfix and not (reason or "").strip():
+        return CommandResult(
+            'FAIL|HOTFIX_REASON_REQUIRED|pass --reason "<text>"',
+            EXIT_VALIDATION,
+        )
+
+    # Defaults to the OS user (PLAN-2.1 F2.1), reversing 2.0's decision to
+    # require it. 2.0 argued that inheriting the environment made an
+    # agent-run approve indistinguishable from a human-run one — but that
+    # was only ever half true, since an agent could pass any string it liked.
+    # The flag never authenticated anyone; it only forced an active choice.
+    #
+    # What it did cost is friction on the one step that must not be
+    # automated, and friction there is precisely what pushes people into
+    # letting the agent run it. This value is audit metadata — who to ask
+    # about this approval later — not proof of who ran the command. The
+    # authentication was, and remains, the harness permission prompt.
+    who = (by or "").strip() or getpass.getuser()
+
+    # Checked before taking the write lock: acquiring it would create the
+    # change directory as a side effect, inventing the change the caller
+    # mistyped.
+    if load_manifest(context, change) is None:
+        return missing_session_result(context, change)
+
+    def _do():
+        m = load_manifest(context, change)
+        if not m:
+            return missing_session_result(context, change)
+
+        lock_phase = m.get("lock_phase", "PLAN")
+        if lock_phase != "PLAN":
+            # Only PLAN -> EXECUTE consumes an approval. Recording one anywhere
+            # else leaves a live sign-off that nothing will spend, waiting to
+            # authorize a transition nobody was asked about.
+            return CommandResult(
+                f"FAIL|APPROVAL_NOT_APPLICABLE|lock_phase={lock_phase}",
+                EXIT_BAD_TRANSITION,
+            )
+
+        approval = {"by": who, "at": datetime.now().isoformat()}
+
+        if not hotfix:
+            m["approval"] = approval
+            save_manifest(context, m, change)
+            return CommandResult(
+                f"SUCCESS|APPROVED|{get_paths(context, change)['change']}|by={who}",
+                EXIT_OK,
+            )
+
+        txn = m.get("transaction", {})
+        if txn.get("txn_status", "idle") == "in_progress":
+            # The open transaction holds a snapshot taken at lock_phase=PLAN.
+            # Jumping the pipeline behind its back means a later rollback
+            # restores a state the change already left, silently undoing the
+            # hotfix.
+            return CommandResult(
+                f"FAIL|TXN_IN_PROGRESS|{txn.get('txn_phase')}",
+                EXIT_LOCK_HELD,
+            )
+
+        approval["hotfix"] = True
+        approval["reason"] = reason.strip()
+        _record_approval(m, approval, "PLAN->EXECUTE (hotfix)")
+
+        m["lock_phase"] = "EXECUTE"
+        # PLAN was skipped, not done. Writing it into completed_phases would
+        # make the manifest claim a plan was produced and reviewed; leaving it
+        # pending would make the pipeline ask for it again.
+        pending = m.get("pending_phases", [])
+        if "PLAN" in pending:
+            pending.remove("PLAN")
+        m["pending_phases"] = pending
+        skipped = m.setdefault("skipped_phases", [])
+        if "PLAN" not in skipped:
+            skipped.append("PLAN")
+
+        save_manifest(context, m, change)
+        return CommandResult(
+            f"SUCCESS|APPROVED_HOTFIX|{get_paths(context, change)['change']}"
+            f"|by={who}|lock_phase=EXECUTE",
+            EXIT_OK,
+        )
+
+    return with_write_lock(context, _do, change=change)
+
+
+def cmd_begin(context, phase, ttl=DEFAULT_TTL, change=None):
+    """Inicia una transacción para la fase dada (PLAN, EXECUTE, VERIFY)."""
+    if phase not in VALID_PHASES:
+        return CommandResult(f"FAIL|INVALID_PHASE|{phase}", EXIT_VALIDATION)
+
+    # A named change that does not exist is a typo, and it is checked here
+    # rather than inside _do because taking the write lock creates the change
+    # directory as a side effect — begin would answer a misspelled name by
+    # bringing that change into being. Only an explicitly named one: with no
+    # --change, creating the manifest below is the documented bootstrap.
+    if change and load_manifest(context, change) is None:
+        return missing_session_result(context, change)
+
+    def _do():
+        p = get_paths(context, change)
+        m = load_manifest(context, change)
+        if not m:
+            m = create_initial_manifest(context, p["change"])
+
+        # DAG enforcement: the manifest decides which phase may start, not the
+        # caller. Without this, the pipeline was only checked on commit — and
+        # an agent that never commits was never stopped.
+        lock_phase = m.get("lock_phase", "PLAN")
+        if phase != lock_phase:
+            return CommandResult(
+                f"FAIL|PHASE_NOT_AUTHORIZED|requested={phase}|lock_phase={lock_phase}",
+                EXIT_BAD_TRANSITION,
+            )
+
+        txn = m.setdefault("transaction", {})
+        status = txn.get("txn_status", "idle")
+        started_at = txn.get("txn_started_at", None)
+
+        if status == "in_progress" and not is_stale(started_at, ttl):
+            return CommandResult(
+                f"FAIL|TXN_IN_PROGRESS|{txn.get('txn_phase')}",
+                EXIT_LOCK_HELD,
+            )
+
+        if phase == "PLAN":
+            _scaffold_artifacts(context, change)
+
+        # Snapshot de estado previo para rollback
+        snapshot = {
+            "current_phase": m.get("current_phase", "PLAN"),
+            "lock_phase": m.get("lock_phase", "PLAN"),
+            "completed_phases": list(m.get("completed_phases", [])),
+            "pending_phases": list(m.get("pending_phases", list(VALID_PHASES))),
+            "session_summary": m.get("session", {}).get("session_summary", ""),
+        }
+
+        txn["txn_status"] = "in_progress"
+        txn["txn_phase"] = phase
+        txn["txn_started_at"] = datetime.now().isoformat()
+        txn["snapshot"] = snapshot
+
+        m["transaction"] = txn
+        save_manifest(context, m, change)
+        return CommandResult(f"SUCCESS|BEGIN|phase={phase}", EXIT_OK)
+
+    return with_write_lock(context, _do, change=change)
+
+
+def cmd_commit(context, next_phase, change=None):
+    """Finaliza exitosamente la transacción y avanza en el DAG de 3 estados."""
+    def _do():
+        m = load_manifest(context, change)
+        if not m:
+            return missing_session_result(context, change)
+
+        txn = m.get("transaction", {})
+        if txn.get("txn_status", "idle") != "in_progress":
+            return CommandResult("FAIL|NO_TXN_IN_PROGRESS", EXIT_GENERIC)
+
+        phase = txn.get("txn_phase")
+        expected_next = TRANSITIONS.get(phase)
+        if expected_next != next_phase:
+            return CommandResult(
+                f"FAIL|BAD_TRANSITION|from={phase}|to={next_phase}|expected={expected_next}",
+                EXIT_BAD_TRANSITION,
+            )
+
+        # Validaciones estrictas (Hard Gates) antes de autorizar el cambio de fase
+        p = get_paths(context, change)
+        base_dir = p["base"]
+
+        if phase == "PLAN" and next_phase == "EXECUTE":
+            required_files = ["objective.md", "tasks.md"]
+            for fname in required_files:
+                fpath = os.path.join(base_dir, fname)
+                if not os.path.exists(fpath):
+                    return CommandResult(
+                        "FAIL|VALIDATION|Debe completar objective.md y tasks.md antes de avanzar a EXECUTE",
+                        EXIT_VALIDATION,
+                    )
+                with open(fpath, "r", encoding="utf-8") as f:
+                    content = f.read()
+                if "[PENDING]" in content:
+                    return CommandResult(
+                        "FAIL|VALIDATION|Debe completar objective.md y tasks.md antes de avanzar a EXECUTE",
+                        EXIT_VALIDATION,
+                    )
+
+            # Checked after the artifacts, deliberately: an approval must not
+            # buy a pass through validation, and a human who signed off on a
+            # still-[PENDING] plan should be told the plan is empty, not that
+            # their approval is missing.
+            if not m.get("approval"):
+                return CommandResult(
+                    "FAIL|APPROVAL_REQUIRED|run `cg approve` before entering EXECUTE",
+                    EXIT_APPROVAL_REQUIRED,
+                )
+
+        elif phase == "VERIFY" and next_phase == "ARCHIVE":
+            required_files = ["review-report.md", "verify-report.md"]
+            for fname in required_files:
+                fpath = os.path.join(base_dir, fname)
+                if not os.path.exists(fpath):
+                    return CommandResult(
+                        "FAIL|VALIDATION|Debe completar la auditoría en review-report.md y verify-report.md antes de archivar",
+                        EXIT_VALIDATION,
+                    )
+                with open(fpath, "r", encoding="utf-8") as f:
+                    content = f.read()
+                if "[PENDING]" in content:
+                    return CommandResult(
+                        "FAIL|VALIDATION|Debe completar la auditoría en review-report.md y verify-report.md antes de archivar",
+                        EXIT_VALIDATION,
+                    )
+
+        # The approval is spent by the transition it authorized, so the next
+        # iteration of the plan needs a new one.
+        if phase == "PLAN" and next_phase == "EXECUTE" and m.get("approval"):
+            _record_approval(m, m["approval"], "PLAN->EXECUTE")
+
+        # Actualizar grafo de fases
+        m["current_phase"] = phase
+        m["lock_phase"] = next_phase
+
+        completed = m.get("completed_phases", [])
+        if phase not in completed:
+            completed.append(phase)
+        m["completed_phases"] = completed
+
+        pending = m.get("pending_phases", [])
+        if phase in pending:
+            pending.remove(phase)
+        m["pending_phases"] = pending
+
+        txn["txn_status"] = "idle"
+        txn["txn_phase"] = "None"
+        txn["txn_started_at"] = None
+        txn.pop("snapshot", None)
+
+        # Generar auto_summary determinístico
+        auto_summary = (
+            f"completed_phase={phase}\n"
+            f"next_phase={next_phase}\n"
+            f"completed={', '.join(completed)}\n"
+            f"pending={', '.join(pending)}"
+        )
+        session_sec = m.setdefault("session", {})
+        session_sec["session_summary"] = auto_summary
+
+        save_manifest(context, m, change)
+        return CommandResult(f"SUCCESS|COMMIT|lock_phase={next_phase}", EXIT_OK)
+
+    return with_write_lock(context, _do, change=change)
+
+
+def cmd_rollback(context, change=None):
+    """Revierte la transacción actual restaurando el snapshot previo."""
+    def _do():
+        m = load_manifest(context, change)
+        if not m:
+            return missing_session_result(context, change)
+
+        txn = m.get("transaction", {})
+        if txn.get("txn_status", "idle") != "in_progress":
+            return CommandResult("FAIL|NO_TXN_IN_PROGRESS", EXIT_GENERIC)
+
+        snapshot = txn.get("snapshot")
+        if snapshot:
+            m["current_phase"] = snapshot.get("current_phase", "PLAN")
+            m["lock_phase"] = snapshot.get("lock_phase", "PLAN")
+            m["completed_phases"] = snapshot.get("completed_phases", [])
+            m["pending_phases"] = snapshot.get("pending_phases", list(VALID_PHASES))
+            if "session_summary" in snapshot:
+                session_sec = m.setdefault("session", {})
+                session_sec["session_summary"] = snapshot["session_summary"]
+
+        txn["txn_status"] = "idle"
+        txn["txn_phase"] = "None"
+        txn["txn_started_at"] = None
+        txn.pop("snapshot", None)
+
+        save_manifest(context, m, change)
+        return CommandResult("SUCCESS|ROLLBACK|restored", EXIT_OK)
+
+    return with_write_lock(context, _do, change=change)
+
+
+def cmd_checkpoint(context, summary, change=None):
+    """Guarda un checkpoint con el resumen de la sesión en manifest.json."""
+    if len(summary) > MAX_SUMMARY_CHARS:
+        return CommandResult(
+            f"FAIL|SUMMARY_TOO_LONG|{len(summary)}/{MAX_SUMMARY_CHARS}",
+            EXIT_VALIDATION,
+        )
+
+    def _do():
+        m = load_manifest(context, change)
+        if not m:
+            return missing_session_result(context, change)
+
+        session_sec = m.setdefault("session", {})
+        session_sec["session_summary"] = summary
+        save_manifest(context, m, change)
+        return CommandResult("SUCCESS|CHECKPOINT_SAVED", EXIT_OK)
+
+    return with_write_lock(context, _do, change=change)

context_guard/mcp_server.py

@@ -0,0 +1,280 @@
+#!/usr/bin/env python3
+"""MCP Server for Context Guard.
+
+Exposes the transactional pipeline of context-guard as native MCP tools
+over stdio transport. All persistent state lives in
+`{context}/.context-guard/manifest.json`, where `context` is the absolute
+path to the project directory.
+
+Pipeline contract (strictly enforced):
+    PLAN  ->  EXECUTE  ->  VERIFY  ->  ARCHIVE
+
+A typical lifecycle:
+    1. begin_transaction("/home/user/my-project", "PLAN")
+    2. save_checkpoint("/home/user/my-project", "objective defined, tasks decomposed")
+    3. commit_transaction("/home/user/my-project", "EXECUTE")
+    4. begin_transaction("/home/user/my-project", "EXECUTE")
+    5. ... work on tasks ...
+    6. save_checkpoint("/home/user/my-project", "all tasks complete")
+    7. commit_transaction("/home/user/my-project", "VERIFY")
+    8. begin_transaction("/home/user/my-project", "VERIFY")
+    9. ... run tests, validate artifacts ...
+    10. commit_transaction("/home/user/my-project", "ARCHIVE")
+"""
+
+import os
+import sys
+
+from mcp.server.fastmcp import FastMCP
+from context_guard.guard.transaction import (
+    cmd_begin,
+    cmd_commit,
+    cmd_rollback,
+    cmd_checkpoint,
+)
+from context_guard.guard.commands import (
+    cmd_check_completion,
+    cmd_next_task,
+    cmd_status,
+    cmd_validate,
+)
+from context_guard.guard.errors import GuardError, EXIT_GENERIC
+
+mcp = FastMCP("context-guard")
+
+
+def _format_result(fn, *args, **kwargs) -> str:
+    """Execute a guard command function, unwrap CommandResult to a readable string."""
+    try:
+        res = fn(*args, **kwargs)
+        return f"[{res.exit_code}] {res.message}"
+    except GuardError as e:
+        return f"[{e.exit_code}] {e.message}"
+    except Exception as e:
+        return f"[{EXIT_GENERIC}] FAIL|UNEXPECTED_ERROR|{str(e)}"
+
+
+@mcp.tool()
+def begin_transaction(context: str, phase: str, change: str | None = None) -> str:
+    """Start a transactional phase in the 3-state pipeline.
+
+    The pipeline enforces strict ordering: PLAN -> EXECUTE -> VERIFY -> ARCHIVE.
+    You must begin a phase before doing work in it, and commit it before
+    advancing to the next. Only one transaction can be active at a time per
+    context; attempting to begin while another is in progress returns an error
+    (unless the existing transaction has expired past its TTL).
+
+    If phase is 'PLAN', this tool automatically scaffolds 5 markdown files in
+    .context-guard/: objective.md, snapshot.md, tasks.md, review-report.md,
+    and verify-report.md with default placeholder text if they do not exist.
+
+    A snapshot of the current manifest state is captured automatically so that
+    rollback_transaction can restore it if the phase fails.
+
+    Args:
+        context: ABSOLUTE PATH to the current project directory
+                 (e.g. /home/user/workspace/my-project).
+        phase: One of 'PLAN', 'EXECUTE', or 'VERIFY'. Any other value is rejected.
+
+        change: OPTIONAL name of the change to operate on. Omit it when the
+                project has exactly one active change; if several are active,
+                omitting it is an error naming them, never a silent guess.
+
+    Returns:
+        '[0] SUCCESS|BEGIN|phase={phase}' on success, or an error string with
+        a non-zero exit code.
+    """
+    return _format_result(cmd_begin, context, phase, change=change)
+
+
+@mcp.tool()
+def commit_transaction(context: str, next_phase: str, change: str | None = None) -> str:
+    """Finalize the active phase and advance the pipeline to the next state.
+
+    Validates that the transition is legal according to the DAG:
+        PLAN -> EXECUTE,  EXECUTE -> VERIFY,  VERIFY -> ARCHIVE.
+    Skipping phases (e.g. PLAN -> VERIFY) is rejected with EXIT_BAD_TRANSITION.
+
+    Phase transitions will be rejected with EXIT_VALIDATION if required artifact
+    files contain '[PENDING]' placeholder text or are missing:
+    - PLAN -> EXECUTE requires completing objective.md and tasks.md.
+    - VERIFY -> ARCHIVE requires completing review-report.md and verify-report.md.
+
+    Committing consolidates state: marks the current phase as completed, updates
+    lock_phase to next_phase, and generates a deterministic auto-summary.
+
+    Args:
+        context: ABSOLUTE PATH to the current project directory
+                 (e.g. /home/user/workspace/my-project).
+        next_phase: The phase to advance to. Must be the legal successor of the
+                    currently active phase ('EXECUTE', 'VERIFY', or 'ARCHIVE').
+
+        change: OPTIONAL name of the change to operate on. Omit it when the
+                project has exactly one active change; if several are active,
+                omitting it is an error naming them, never a silent guess.
+
+    Returns:
+        '[0] SUCCESS|COMMIT|lock_phase={next_phase}' on success, or an error
+        string with a non-zero exit code.
+    """
+    return _format_result(cmd_commit, context, next_phase, change=change)
+
+
+@mcp.tool()
+def rollback_transaction(context: str, change: str | None = None) -> str:
+    """Abort the active transaction and restore the pre-begin manifest snapshot.
+
+    Use this when a phase fails (e.g. tests don't pass during VERIFY, or an
+    execution step produces broken state). The manifest is rolled back to
+    exactly the state it was in before begin_transaction was called, and the
+    transaction status is reset to idle.
+
+    Args:
+        context: ABSOLUTE PATH to the current project directory
+                 (e.g. /home/user/workspace/my-project).
+
+        change: OPTIONAL name of the change to operate on. Omit it when the
+                project has exactly one active change; if several are active,
+                omitting it is an error naming them, never a silent guess.
+
+    Returns:
+        '[0] SUCCESS|ROLLBACK|restored' on success, or an error string with a
+        non-zero exit code if no transaction is in progress.
+    """
+    return _format_result(cmd_rollback, context, change=change)
+
+
+@mcp.tool()
+def save_checkpoint(context: str, summary: str, change: str | None = None) -> str:
+    """Persist a session summary as a lightweight checkpoint in manifest.json.
+
+    Checkpoints serve as warm-boot state: if the agent loses context (e.g.
+    session timeout, token limit), it can read the last checkpoint to resume.
+    The summary is stored in manifest.json under session.session_summary.
+
+    Note: commit_transaction also writes an auto-generated checkpoint, so
+    manual checkpoints are mainly useful mid-phase to record intermediate
+    progress before committing.
+
+    Args:
+        context: ABSOLUTE PATH to the current project directory
+                 (e.g. /home/user/workspace/my-project).
+        summary: Free-form text summarizing current progress. Maximum 2000
+                 characters (~500 tokens). Exceeding the limit returns
+                 EXIT_VALIDATION.
+
+        change: OPTIONAL name of the change to operate on. Omit it when the
+                project has exactly one active change; if several are active,
+                omitting it is an error naming them, never a silent guess.
+
+    Returns:
+        '[0] SUCCESS|CHECKPOINT_SAVED' on success, or an error string with a
+        non-zero exit code.
+    """
+    return _format_result(cmd_checkpoint, context, summary, change=change)
+
+
+@mcp.tool()
+def get_status(context: str, change: str | None = None) -> str:
+    """Read the whole state of a change in one call, for warm-boot rehydration.
+
+    Returns the context name, the first line of objective.md, task progress as
+    completed/total, the next unclaimed pending task, and whether the session
+    lock is held. This is the tool to call first after losing context: it is
+    cheaper than reading the artifacts and it never guesses.
+
+    Args:
+        context: ABSOLUTE PATH to the current project directory.
+        change: OPTIONAL name of the change to operate on. Omit it when the
+                project has exactly one active change; if several are active,
+                omitting it is an error naming them, never a silent guess.
+
+    Returns:
+        '[0] CONTEXT: ... / OBJECTIVE: ... / PROGRESS: n/m tasks complete /
+        NEXT: ... / LOCK: ...' on success.
+    """
+    return _format_result(cmd_status, context, change)
+
+
+@mcp.tool()
+def check_completion(context: str, change: str | None = None) -> str:
+    """Count the checkboxes in tasks.md deterministically.
+
+    Use this instead of counting by eye before advancing a phase — the parser
+    is the source of truth for whether the work is done, and it does not
+    hallucinate a total.
+
+    Args:
+        context: ABSOLUTE PATH to the current project directory.
+        change: OPTIONAL name of the change to operate on. Omit it when the
+                project has exactly one active change; if several are active,
+                omitting it is an error naming them, never a silent guess.
+
+    Returns:
+        '[0] source=tasks.md / total=N / completed=M / all_complete=true|false'.
+    """
+    return _format_result(cmd_check_completion, context, change)
+
+
+@mcp.tool()
+def validate(context: str, change: str | None = None) -> str:
+    """Lint the session artifacts: existence, size cap, and language.
+
+    Requires objective.md, snapshot.md and tasks.md to exist; checks every
+    artifact against the size cap and rejects Spanish text (artifacts are
+    English by contract). Does NOT check for leftover '[PENDING]' markers —
+    that is enforced by commit_transaction.
+
+    Args:
+        context: ABSOLUTE PATH to the current project directory.
+        change: OPTIONAL name of the change to operate on. Omit it when the
+                project has exactly one active change; if several are active,
+                omitting it is an error naming them, never a silent guess.
+
+    Returns:
+        '[0] SUCCESS|VALIDATE_OK', or '[4]' followed by one FAIL line per
+        problem found.
+    """
+    return _format_result(cmd_validate, context, None, change)
+
+
+@mcp.tool()
+def next_task(context: str, change: str | None = None,
+              agent_id: str | None = None) -> str:
+    """Claim the next pending task in tasks.md and return it.
+
+    Not read-only: the claim is taken atomically as part of the same call,
+    which is what makes it safe for several agents to work one change at once.
+    The returned agent_id is the identity that won the claim — keep it, since
+    releasing the task requires passing it back.
+
+    Claims carry a lease; a task whose lease expired is treated as abandoned
+    and handed to the next caller, with the takeover recorded in the manifest.
+
+    Args:
+        context: ABSOLUTE PATH to the current project directory.
+        change: OPTIONAL name of the change to operate on. Omit it when the
+                project has exactly one active change; if several are active,
+                omitting it is an error naming them, never a silent guess.
+        agent_id: OPTIONAL identity to claim as. Generated if omitted.
+
+    Returns:
+        '[0] SUCCESS|NEXT_TASK|{task_id}|{agent_id}|{description}', or
+        '[0] DONE|NO_PENDING_TASKS' when nothing is left.
+    """
+    return _format_result(cmd_next_task, context, agent_id, change)
+
+
+# Deliberately NOT exposed as a tool: `approve`. PLAN.md 0.6 names the
+# harness's permission prompt on `cg approve` as the only hard control in the
+# enforcement model, and an MCP tool is precisely the channel that routes
+# around it. The MCP is a transport; the human's confirmation is not.
+
+
+def main():
+    """Run FastMCP server over stdio transport."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()