arqux 1.0.0__py3-none-any.whl

arqux/__init__.py

@@ -0,0 +1,28 @@
+"""
+Arqux — Minimum-viable governance framework for AI agent teams.
+
+Public API surface:
+    - `cli.main()` — entry point for the `arqux` console script.
+    - `server.serve()` — start the MCP server.
+    - `__version__` — package version string.
+
+The framework exposes 24 MCP handlers grouped in 6 modules:
+    workspace, project, cycle, task, evidence, protocol.
+
+See `AGENTS.md` for the single-entry-point documentation.
+"""
+
+from .constants import (
+    ARQUX_DIR,
+    ARQUX_VERSION,
+    PRODUCT_NAME,
+)
+
+__version__ = ARQUX_VERSION
+
+__all__ = [
+    "PRODUCT_NAME",
+    "ARQUX_DIR",
+    "ARQUX_VERSION",
+    "__version__",
+]

arqux/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m arqux`."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

arqux/cli.py

@@ -0,0 +1,102 @@
+"""CLI entry point.
+
+Exposes three commands:
+    arqux serve    — start the MCP server on stdio.
+    arqux init     — initialize .arqux/ in the current directory.
+    arqux status   — print workspace/project/cycle status.
+    arqux --version
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Sequence
+
+import click
+
+from . import __version__
+from .constants import PRODUCT_NAME, PRODUCT_NAME_TITLE
+
+
+@click.group(
+    help=f"{PRODUCT_NAME_TITLE} — minimum-viable governance framework for AI agent teams."
+)
+@click.version_option(version=__version__, prog_name=PRODUCT_NAME)
+def cli() -> None:
+    """Top-level command group."""
+
+
+@cli.command(help="Start the MCP server on stdio.")
+@click.option(
+    "--verbose",
+    is_flag=True,
+    default=False,
+    help="Log handler invocations to stderr (for debugging).",
+)
+def serve(verbose: bool) -> None:
+    """Start the MCP server."""
+    # Import lazily so `--version` and `--help` do not require MCP deps.
+    from .server import run_server
+
+    run_server(verbose=verbose)
+
+
+@cli.command(help="Initialize .arqux/ in the current directory.")
+@click.option(
+    "--workspace",
+    is_flag=True,
+    default=False,
+    help="Initialize as a workspace root (creates meta-brain + projects index).",
+)
+@click.option(
+    "--project",
+    "project_name",
+    default=None,
+    help="Register the current directory as a project with this name.",
+)
+def init(workspace: bool, project_name: str | None) -> None:
+    """Initialize governance in the current directory."""
+    from .handlers.workspace import init_workspace
+    from .handlers.project import init_project
+
+    if not workspace and project_name is None:
+        # Default: initialize as both workspace and a project named "default".
+        workspace = True
+        project_name = "default"
+
+    if workspace:
+        result = init_workspace(path=".", verbose=True)
+        click.echo(result.to_text())
+
+    if project_name is not None:
+        result = init_project(name=project_name, path=".", verbose=True)
+        click.echo(result.to_text())
+
+
+@cli.command(help="Print workspace/project/cycle status.")
+@click.option(
+    "--profile",
+    type=click.Choice(["OUT-MIN", "OUT-WORK", "OUT-AUDIT", "OUT-FULL"]),
+    default="OUT-WORK",
+    help="CORTEX-OUT profile to use for the output.",
+)
+def status(profile: str) -> None:
+    """Print current status."""
+    from .cortex_out import format_status
+    from .state import find_workspace_root
+
+    root = find_workspace_root()
+    if root is None:
+        click.echo(f"ERROR code=NOT_FOUND reason=no_workspace_init")
+        sys.exit(1)
+
+    click.echo(format_status(root, profile=profile))
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Console-script entry point."""
+    cli(args=list(argv) if argv is not None else None)
+
+
+if __name__ == "__main__":
+    main()

arqux/constants.py

@@ -0,0 +1,184 @@
+"""Module-level constants for Arqux.
+
+All placeholder-derived identifiers live here so the rename script has a single
+canonical surface to swap. After running `scripts/rename-product.py <name>`:
+
+    arqux            -> <name>           (lowercase, package/cli/paths)
+    ARQUX      -> <NAME>           (uppercase, constants/markers)
+    Arqux      -> <Name>           (title case, display names)
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# --- Identity --------------------------------------------------------------
+
+#: Lowercase product name. Used as the package name, CLI command, and the
+#: governance directory name (e.g. `.<product>/`).
+PRODUCT_NAME: str = "arqux"
+
+#: Uppercase product name. Used for environment variables and constants.
+PRODUCT_NAME_UPPER: str = "ARQUX"
+
+#: Title-case product name. Used in human-readable documentation.
+PRODUCT_NAME_TITLE: str = "Arqux"
+
+#: Version string — single source of truth.
+ARQUX_VERSION: str = "1.0.0"
+
+# --- Filesystem layout -----------------------------------------------------
+
+#: Name of the governance directory created inside a workspace or project.
+ARQUX_DIR: str = f".{PRODUCT_NAME}"
+
+#: Environment variable prefix for runtime configuration.
+ARQUX_ENV_PREFIX: str = f"{PRODUCT_NAME_UPPER}_"
+
+#: Default workspace manifest file (machine-readable).
+MANIFEST_CORTEX: str = "manifest.cortex"
+
+#: Default workspace manifest file (human-readable).
+MANIFEST_HCORTEX: str = "manifest.md"
+
+#: Workspace-level projects index (machine-readable).
+PROJECTS_CORTEX: str = "projects.cortex"
+
+#: Workspace-level projects index (human-readable).
+PROJECTS_HCORTEX: str = "projects.md"
+
+#: Project-level brain (machine-readable).
+BRAIN_CORTEX: str = "brain.cortex"
+
+#: Project-level brain (human-readable).
+BRAIN_HCORTEX: str = "brain.md"
+
+#: Workspace-level meta-brain (machine-readable).
+META_BRAIN_CORTEX: str = "meta-brain.cortex"
+
+#: Workspace-level meta-brain (human-readable).
+META_BRAIN_HCORTEX: str = "meta-brain.md"
+
+#: Per-cycle tasks directory.
+TASKS_DIR: str = "tasks"
+
+#: Per-project cycles directory.
+CYCLES_DIR: str = "cycles"
+
+# --- Brain sections (the project brain is the single shared mind) -----------
+#
+# The brain.cortex is the shared project mind. All handoffs, pulses,
+# sessions, lessons, focus, and active context live HERE — not in separate
+# files. This guarantees that every agent bound to the project shares the
+# same mental state.
+
+BRAIN_SECTION_FOCUS: str = "FOCUS"
+BRAIN_SECTION_OBJECTIVES: str = "OBJECTIVES"
+BRAIN_SECTION_SESSIONS: str = "SESSIONS"
+BRAIN_SECTION_HANDOFFS: str = "HANDOFFS"
+BRAIN_SECTION_PULSE: str = "PULSE"
+BRAIN_SECTION_LESSONS: str = "LESSONS"
+BRAIN_SECTION_ACTIVE_CONTEXT: str = "ACTIVE_CONTEXT"
+BRAIN_SECTION_RISKS: str = "RISKS"
+BRAIN_SECTION_CONCURRENCY: str = "CONCURRENCY"
+
+#: All canonical brain sections (used for validation).
+ALL_BRAIN_SECTIONS: tuple[str, ...] = (
+    BRAIN_SECTION_FOCUS,
+    BRAIN_SECTION_OBJECTIVES,
+    BRAIN_SECTION_SESSIONS,
+    BRAIN_SECTION_HANDOFFS,
+    BRAIN_SECTION_PULSE,
+    BRAIN_SECTION_LESSONS,
+    BRAIN_SECTION_ACTIVE_CONTEXT,
+    BRAIN_SECTION_RISKS,
+    BRAIN_SECTION_CONCURRENCY,
+)
+
+# --- Roles and permissions -------------------------------------------------
+
+ROLE_GOVERNOR: str = "governor"
+ROLE_EXECUTOR: str = "executor"
+ROLE_AUDITOR: str = "auditor"
+
+ALL_ROLES: tuple[str, ...] = (ROLE_GOVERNOR, ROLE_EXECUTOR, ROLE_AUDITOR)
+
+# --- Task state machine ----------------------------------------------------
+
+TASK_DRAFT: str = "draft"
+TASK_OPEN: str = "open"
+TASK_IN_PROGRESS: str = "in_progress"
+TASK_REVIEW: str = "review"
+TASK_DONE: str = "done"
+TASK_BLOCKED: str = "blocked"
+TASK_CANCELLED: str = "cancelled"
+
+TASK_ACTIVE_STATES: tuple[str, ...] = (
+    TASK_DRAFT,
+    TASK_OPEN,
+    TASK_IN_PROGRESS,
+    TASK_REVIEW,
+    TASK_BLOCKED,
+)
+
+TASK_TERMINAL_STATES: tuple[str, ...] = (TASK_DONE, TASK_CANCELLED)
+
+TASK_TRANSITIONS: dict[str, tuple[str, ...]] = {
+    TASK_DRAFT: (TASK_OPEN, TASK_CANCELLED),
+    TASK_OPEN: (TASK_IN_PROGRESS, TASK_CANCELLED),
+    TASK_IN_PROGRESS: (TASK_REVIEW, TASK_BLOCKED, TASK_DONE, TASK_CANCELLED),
+    TASK_REVIEW: (TASK_DONE, TASK_IN_PROGRESS, TASK_BLOCKED, TASK_CANCELLED),
+    TASK_BLOCKED: (TASK_IN_PROGRESS, TASK_CANCELLED),
+    TASK_DONE: (),
+    TASK_CANCELLED: (),
+}
+
+# --- Cycle state machine ---------------------------------------------------
+
+CYCLE_OPEN: str = "open"
+CYCLE_CLOSED: str = "closed"
+
+CYCLE_TRANSITIONS: dict[str, tuple[str, ...]] = {
+    CYCLE_OPEN: (CYCLE_CLOSED,),
+    CYCLE_CLOSED: (),
+}
+
+# --- CORTEX-OUT profiles ---------------------------------------------------
+
+OUT_MIN: str = "OUT-MIN"
+OUT_WORK: str = "OUT-WORK"
+OUT_AUDIT: str = "OUT-AUDIT"
+OUT_FULL: str = "OUT-FULL"
+OUT_ERROR: str = "OUT-ERROR"
+
+ALL_OUT_PROFILES: tuple[str, ...] = (
+    OUT_MIN,
+    OUT_WORK,
+    OUT_AUDIT,
+    OUT_FULL,
+    OUT_ERROR,
+)
+
+DEFAULT_OUT_PROFILE: str = OUT_WORK
+
+# --- Error codes -----------------------------------------------------------
+
+PERMISSION_DENIED: str = "PERMISSION_DENIED"
+NOT_FOUND: str = "NOT_FOUND"
+INVALID_STATE: str = "INVALID_STATE"
+INVALID_ARGUMENT: str = "INVALID_ARGUMENT"
+ALREADY_EXISTS: str = "ALREADY_EXISTS"
+INTERNAL_ERROR: str = "INTERNAL_ERROR"
+
+# --- Paths -----------------------------------------------------------------
+
+PACKAGE_ROOT: Path = Path(__file__).resolve().parent
+TEMPLATES_DIR: Path = PACKAGE_ROOT / "templates"
+IDENTITIES_DIR: Path = PACKAGE_ROOT / "identities"
+
+# --- Environment overrides -------------------------------------------------
+
+def env(var: str, default: str | None = None) -> str | None:
+    """Read an environment variable prefixed with the product name."""
+    return os.environ.get(f"{ARQUX_ENV_PREFIX}{var}", default)

arqux/cortex_out.py

@@ -0,0 +1,124 @@
+"""CORTEX-OUT output protocol.
+
+Five profiles, picked by context:
+
+    OUT-MIN     — quick acks, no detail.
+    OUT-WORK    — work updates, deliverables, evidence of progress.
+    OUT-AUDIT   — architecture reviews, decision logs.
+    OUT-FULL    — full prose, no compression (for humans).
+    OUT-ERROR   — failures, blockers, permission denials.
+
+Format: <PROFILE> <key=value>... [message]
+
+Examples:
+    OUT-MIN ok T-001 in_progress
+    OUT-WORK done T-001 evidence=E-007 coverage=87%
+    OUT-AUDIT review cycle=CYCLE-01 risk=low rationale="..."
+    OUT-ERROR code=PERMISSION_DENIED handler=task.create reason=executor_role
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .constants import (
+    DEFAULT_OUT_PROFILE,
+    OUT_AUDIT,
+    OUT_ERROR,
+    OUT_FULL,
+    OUT_MIN,
+    OUT_WORK,
+)
+
+
+@dataclass
+class CortexOUT:
+    """A structured CORTEX-OUT response."""
+
+    profile: str
+    fields: dict[str, Any] = field(default_factory=dict)
+    message: str = ""
+
+    @classmethod
+    def profile(cls, profile: str, message: str = "", **fields: Any) -> "CortexOUT":
+        """Build a CORTEX-OUT response with the given profile."""
+        return cls(profile=profile, fields=dict(fields), message=message)
+
+    @classmethod
+    def min(cls, message: str = "", **fields: Any) -> "CortexOUT":
+        return cls(profile=OUT_MIN, fields=dict(fields), message=message)
+
+    @classmethod
+    def work(cls, message: str = "", **fields: Any) -> "CortexOUT":
+        return cls(profile=OUT_WORK, fields=dict(fields), message=message)
+
+    @classmethod
+    def audit(cls, message: str = "", **fields: Any) -> "CortexOUT":
+        return cls(profile=OUT_AUDIT, fields=dict(fields), message=message)
+
+    @classmethod
+    def full(cls, message: str = "", **fields: Any) -> "CortexOUT":
+        return cls(profile=OUT_FULL, fields=dict(fields), message=message)
+
+    @classmethod
+    def error(cls, message: str = "", **fields: Any) -> "CortexOUT":
+        return cls(profile=OUT_ERROR, fields=dict(fields), message=message)
+
+    def to_text(self) -> str:
+        """Render as a single text line (or multi-line for OUT-FULL)."""
+        if self.profile == OUT_FULL:
+            # OUT-FULL: just the message, no key=value compression.
+            return self.message
+
+        parts: list[str] = [self.profile]
+        for key, value in self.fields.items():
+            parts.append(f"{key}={self._format_value(value)}")
+        if self.message:
+            parts.append(self.message)
+        return " ".join(parts)
+
+    @staticmethod
+    def _format_value(value: Any) -> str:
+        if isinstance(value, bool):
+            return "true" if value else "false"
+        if isinstance(value, (list, tuple)):
+            return ",".join(str(v) for v in value)
+        if isinstance(value, dict):
+            return ";".join(f"{k}:{v}" for k, v in value.items())
+        return str(value)
+
+
+def format_status(workspace_root: Any, profile: str = DEFAULT_OUT_PROFILE) -> str:
+    """Format a workspace status report using the requested CORTEX-OUT profile."""
+    from pathlib import Path
+
+    root: Path = workspace_root
+
+    if profile == OUT_MIN:
+        return f"OUT-MIN workspace={root.name} projects=? cycles=? tasks=?"
+
+    if profile == OUT_WORK:
+        return (
+            f"OUT-WORK workspace={root.name} "
+            f"manifest={'yes' if (root / 'manifest.cortex').exists() else 'no'} "
+            f"projects={'yes' if (root / 'projects.cortex').exists() else 'no'}"
+        )
+
+    if profile == OUT_AUDIT:
+        lines = [f"OUT-AUDIT workspace={root.name}"]
+        for child in sorted(root.iterdir()):
+            if child.is_dir():
+                lines.append(f"  dir={child.name}")
+            elif child.is_file():
+                lines.append(f"  file={child.name}")
+        return "\n".join(lines)
+
+    if profile == OUT_FULL:
+        return (
+            f"Workspace at {root}\n\n"
+            f"This workspace is governed by the framework. The manifest "
+            f"and projects index live in this directory."
+        )
+
+    return CortexOUT.error(message="unknown profile").to_text()