getcalx 0.1.0__tar.gz

getcalx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spencer Hardwick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

getcalx-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: getcalx
+Version: 0.1.0
+Summary: Behavioral governance layer for AI coding agents. Makes corrections compound.
+Author: Spencer Hardwick
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.30; extra == "llm"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# Calx
+
+Behavioral governance layer for AI coding agents. Makes corrections compound.
+
+Calx captures the corrections you make to AI agents, detects when the same mistake recurs, and promotes recurring corrections into rules that get injected at the start of every session. Your agent stops making the same mistake twice.
+
+## The problem
+
+You correct an AI agent. It learns -- for that session. Next session, same mistake. You correct it again. The correction doesn't transfer between sessions, between agents, or between projects. Your knowledge leaks.
+
+## How Calx works
+
+1. **Capture** -- `calx correct "don't mock the database in integration tests"` logs the correction to an append-only event log (`corrections.jsonl`)
+2. **Detect** -- Calx matches new corrections against existing ones. When the same correction recurs 3+ times, it surfaces for promotion
+3. **Promote** -- Recurring corrections become rules, written to `.calx/rules/{domain}.md`
+4. **Inject** -- At session start, all active rules are injected into the agent's context via hooks
+
+This is the **learning loop**: correct -> detect recurrence -> promote to rule -> inject at session start -> fewer corrections needed.
+
+## Install
+
+```bash
+pip install getcalx
+```
+
+## Quick start
+
+```bash
+# Initialize Calx in your project
+calx init
+
+# Log a correction
+calx correct "always validate API inputs before processing"
+
+# Check status
+calx status
+
+# Run distillation (promote recurring corrections to rules)
+calx distill
+
+# View health of your rule set
+calx health score
+```
+
+## Architecture
+
+```
+.calx/
+├── calx.json              # Configuration
+├── .gitignore              # Tracks what to commit vs ignore
+├── corrections.jsonl       # Append-only event log (local, gitignored)
+├── rules/
+│   └── {domain}.md         # Promoted rules per domain (committed)
+├── health/
+│   ├── state.json          # Health scores
+│   └── .last_clean_exit    # Session state marker
+└── method/
+    ├── how-we-document.md  # Learning loop methodology
+    ├── orchestration.md    # Hook and session management
+    ├── dispatch.md         # Agent dispatch scaffolding
+    └── review.md           # Review process
+```
+
+**Event-sourced corrections** -- `corrections.jsonl` is truly append-only. State is derived by replaying events. No rewrites, no mutations.
+
+**Three-tier distillation:**
+- **Tier 1** -- Silent recurrence counter (automatic)
+- **Tier 2** -- Binary promote/reject at threshold (developer approves)
+- **Tier 3** -- Weekly review of rule effectiveness
+
+**Hook-based orchestration:**
+- `session-start` -- Rule injection, dirty exit check, effectiveness signal, token discipline
+- `session-end` -- Uncommitted changes check, undistilled reminder, clean exit marker
+- `orientation-gate` / `collapse-guard` -- Pure bash PreToolUse hooks (no Python on the hot path). `collapse-guard` uses `jq` if available (falls back silently without it)
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `calx init` | Initialize Calx in current project |
+| `calx correct <text>` | Log a correction |
+| `calx status` | Show project status |
+| `calx distill` | Promote recurring corrections to rules |
+| `calx config` | View or modify configuration |
+| `calx health` | Health analysis (score, conflicts, staleness, dedup, coverage, conversion) |
+| `calx dispatch` | Generate dispatch prompt for a domain agent |
+| `calx stats` | Show local metrics |
+
+## Development
+
+```bash
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint
+ruff check src/ tests/
+
+# Type check
+mypy src/calx/
+```
+
+## License
+
+MIT

getcalx-0.1.0/README.md

@@ -0,0 +1,107 @@
+# Calx
+
+Behavioral governance layer for AI coding agents. Makes corrections compound.
+
+Calx captures the corrections you make to AI agents, detects when the same mistake recurs, and promotes recurring corrections into rules that get injected at the start of every session. Your agent stops making the same mistake twice.
+
+## The problem
+
+You correct an AI agent. It learns -- for that session. Next session, same mistake. You correct it again. The correction doesn't transfer between sessions, between agents, or between projects. Your knowledge leaks.
+
+## How Calx works
+
+1. **Capture** -- `calx correct "don't mock the database in integration tests"` logs the correction to an append-only event log (`corrections.jsonl`)
+2. **Detect** -- Calx matches new corrections against existing ones. When the same correction recurs 3+ times, it surfaces for promotion
+3. **Promote** -- Recurring corrections become rules, written to `.calx/rules/{domain}.md`
+4. **Inject** -- At session start, all active rules are injected into the agent's context via hooks
+
+This is the **learning loop**: correct -> detect recurrence -> promote to rule -> inject at session start -> fewer corrections needed.
+
+## Install
+
+```bash
+pip install getcalx
+```
+
+## Quick start
+
+```bash
+# Initialize Calx in your project
+calx init
+
+# Log a correction
+calx correct "always validate API inputs before processing"
+
+# Check status
+calx status
+
+# Run distillation (promote recurring corrections to rules)
+calx distill
+
+# View health of your rule set
+calx health score
+```
+
+## Architecture
+
+```
+.calx/
+├── calx.json              # Configuration
+├── .gitignore              # Tracks what to commit vs ignore
+├── corrections.jsonl       # Append-only event log (local, gitignored)
+├── rules/
+│   └── {domain}.md         # Promoted rules per domain (committed)
+├── health/
+│   ├── state.json          # Health scores
+│   └── .last_clean_exit    # Session state marker
+└── method/
+    ├── how-we-document.md  # Learning loop methodology
+    ├── orchestration.md    # Hook and session management
+    ├── dispatch.md         # Agent dispatch scaffolding
+    └── review.md           # Review process
+```
+
+**Event-sourced corrections** -- `corrections.jsonl` is truly append-only. State is derived by replaying events. No rewrites, no mutations.
+
+**Three-tier distillation:**
+- **Tier 1** -- Silent recurrence counter (automatic)
+- **Tier 2** -- Binary promote/reject at threshold (developer approves)
+- **Tier 3** -- Weekly review of rule effectiveness
+
+**Hook-based orchestration:**
+- `session-start` -- Rule injection, dirty exit check, effectiveness signal, token discipline
+- `session-end` -- Uncommitted changes check, undistilled reminder, clean exit marker
+- `orientation-gate` / `collapse-guard` -- Pure bash PreToolUse hooks (no Python on the hot path). `collapse-guard` uses `jq` if available (falls back silently without it)
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `calx init` | Initialize Calx in current project |
+| `calx correct <text>` | Log a correction |
+| `calx status` | Show project status |
+| `calx distill` | Promote recurring corrections to rules |
+| `calx config` | View or modify configuration |
+| `calx health` | Health analysis (score, conflicts, staleness, dedup, coverage, conversion) |
+| `calx dispatch` | Generate dispatch prompt for a domain agent |
+| `calx stats` | Show local metrics |
+
+## Development
+
+```bash
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint
+ruff check src/ tests/
+
+# Type check
+mypy src/calx/
+```
+
+## License
+
+MIT

getcalx-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "getcalx"
+version = "0.1.0"
+description = "Behavioral governance layer for AI coding agents. Makes corrections compound."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    {name = "Spencer Hardwick"}
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "click>=8.1",
+]
+
+[project.optional-dependencies]
+llm = ["anthropic>=0.30"]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[project.scripts]
+calx = "calx.cli.main:cli"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+calx = ["hooks/templates/*.sh"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"

getcalx-0.1.0/setup.cfg

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

getcalx-0.1.0/src/calx/__init__.py

@@ -0,0 +1,3 @@
+"""Calx — behavioral governance layer for AI coding agents."""
+
+__version__ = "0.1.0"

getcalx-0.1.0/src/calx/__main__.py

@@ -0,0 +1,3 @@
+from calx.cli.main import cli
+
+cli()

getcalx-0.1.0/src/calx/capture/__init__.py

@@ -0,0 +1 @@
+"""Capture layer — explicit corrections, session-end prompts, recovery."""

getcalx-0.1.0/src/calx/capture/explicit.py

@@ -0,0 +1,99 @@
+"""Explicit correction capture — ``calx correct [message]``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from calx.core.config import load_config
+from calx.core.corrections import CorrectionState, create_correction
+
+
+def capture_explicit(
+    calx_dir: Path,
+    message: str,
+    domain: str | None = None,
+    correction_type: str = "process",
+    context: str = "",
+) -> tuple[CorrectionState, str]:
+    """Capture an explicit correction and return (correction, feedback).
+
+    Domain resolution order:
+    1. Explicit ``domain`` argument
+    2. Auto-detect from cwd
+    3. First domain in config
+    """
+    config = load_config(calx_dir)
+
+    resolved_domain = domain or _auto_detect_domain(calx_dir) or _first_domain(config)
+
+    correction = create_correction(
+        calx_dir,
+        domain=resolved_domain,
+        description=message,
+        correction_type=correction_type,
+        context=context,
+        source="explicit",
+    )
+
+    # Try recurrence check — distillation module may not exist yet
+    feedback = f"Logged as {correction.id} in {resolved_domain} domain."
+    try:
+        from calx.core.corrections import materialize
+        from calx.distillation.recurrence import check_recurrence
+
+        result = check_recurrence(calx_dir, correction)
+        if result.is_recurrence and result.original_id:
+            # Look up the original correction's description
+            all_corr = materialize(calx_dir)
+            by_id = {c.id: c for c in all_corr}
+            original = by_id.get(result.original_id)
+            original_desc = original.description if original else result.original_id
+            count = result.new_count
+
+            threshold = config.promotion_threshold
+            if count >= threshold:
+                feedback = (
+                    f'Logged. Matches {result.original_id}: "{original_desc}". '
+                    f"({count} occurrence — promotion eligible.)"
+                )
+            else:
+                feedback = (
+                    f'Logged. Matches {result.original_id}: "{original_desc}". '
+                    f"({count} occurrences.)"
+                )
+    except ImportError:
+        pass
+
+    return correction, feedback
+
+
+def _auto_detect_domain(calx_dir: Path) -> str | None:
+    """Infer domain from cwd relative to the project root.
+
+    The project root is the parent of the ``.calx`` directory.
+    If cwd is inside a subdirectory whose name matches a configured domain,
+    that domain is returned.
+    """
+    config = load_config(calx_dir)
+    if not config.domains:
+        return None
+
+    project_root = calx_dir.parent
+    try:
+        cwd = Path.cwd()
+        relative = cwd.relative_to(project_root)
+    except ValueError:
+        return None
+
+    parts = relative.parts
+    for part in parts:
+        if part in config.domains:
+            return part
+
+    return None
+
+
+def _first_domain(config: object) -> str:
+    """Return the first configured domain, or 'general' as fallback."""
+    domains = getattr(config, "domains", [])
+    return domains[0] if domains else "general"

getcalx-0.1.0/src/calx/capture/recovery.py

@@ -0,0 +1,25 @@
+"""Dirty-exit recovery check at session start."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from calx.core.state import check_clean_exit
+
+
+def recovery_check(calx_dir: Path) -> str | None:
+    """Check whether the previous session exited cleanly.
+
+    Returns a recovery prompt message if the exit was dirty,
+    or ``None`` if everything is fine.
+    """
+    status = check_clean_exit(calx_dir)
+
+    if status.was_clean:
+        return None
+
+    return (
+        "Previous session did not exit cleanly. "
+        "There may be undistilled corrections or uncommitted changes. "
+        "Run `calx status` to review."
+    )

getcalx-0.1.0/src/calx/capture/session_end.py

@@ -0,0 +1,69 @@
+"""Session-end capture prompt. Called by the session-end hook."""
+
+from __future__ import annotations
+
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+from calx.core.corrections import get_undistilled
+from calx.core.events import Event, log_event
+from calx.core.state import write_clean_exit
+
+
+def session_end_prompt(calx_dir: Path) -> str:
+    """Generate a session-end summary and write clean-exit marker.
+
+    Steps:
+    1. Count undistilled corrections
+    2. Check for uncommitted git changes
+    3. Write clean-exit marker
+    4. Log session_end event
+    5. Return formatted message
+    """
+    undistilled = get_undistilled(calx_dir)
+    uncommitted = _has_uncommitted_changes(calx_dir)
+
+    write_clean_exit(calx_dir)
+
+    log_event(calx_dir, Event(
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        event="session_end",
+        data={
+            "undistilled_count": len(undistilled),
+            "uncommitted_changes": uncommitted,
+        },
+    ))
+
+    parts: list[str] = []
+
+    if undistilled:
+        ids = ", ".join(c.id for c in undistilled)
+        parts.append(
+            f"{len(undistilled)} undistilled correction(s): {ids}. "
+            "Consider running `calx distill`."
+        )
+
+    if uncommitted:
+        parts.append("Uncommitted changes detected. Consider committing before exit.")
+
+    if not parts:
+        return "Session ended cleanly. No pending items."
+
+    return "Session end summary:\n" + "\n".join(f"- {p}" for p in parts)
+
+
+def _has_uncommitted_changes(calx_dir: Path) -> bool:
+    """Check for uncommitted git changes in the project root."""
+    project_root = calx_dir.parent
+    try:
+        result = subprocess.run(
+            ["git", "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+            cwd=str(project_root),
+            timeout=5,
+        )
+        return bool(result.stdout.strip())
+    except (subprocess.SubprocessError, FileNotFoundError, OSError):
+        return False

getcalx-0.1.0/src/calx/cli/__init__.py

@@ -0,0 +1 @@
+"""Calx CLI package."""

getcalx-0.1.0/src/calx/cli/config_cmd.py

@@ -0,0 +1,71 @@
+"""calx config — settings management."""
+from __future__ import annotations
+
+import click
+
+from calx.core.config import find_calx_dir, load_config, save_config
+
+
+@click.command("config")
+@click.option("--show", is_flag=True, help="Show current config")
+@click.option("--set", "key_value", nargs=2, help="Set a config value: --set key value")
+def config_cmd(show: bool, key_value: tuple[str, str] | None):
+    """View or modify Calx configuration."""
+    calx_dir = find_calx_dir()
+    if not calx_dir:
+        click.echo("Not a Calx project. Run `calx init` first.", err=True)
+        raise SystemExit(1)
+
+    config = load_config(calx_dir)
+
+    if key_value:
+        key, value = key_value
+        _set_config(calx_dir, config, key, value)
+    else:
+        # Default to showing config
+        click.echo("Calx Config")
+        click.echo(f"  Domains: {', '.join(config.domains)}")
+        click.echo(f"  Agent naming: {config.agent_naming}")
+        click.echo(f"  Promotion threshold: {config.promotion_threshold}")
+        click.echo(f"  Max prompts/session: {config.max_prompts_per_session}")
+        click.echo(f"  Staleness days: {config.staleness_days}")
+        click.echo(f"  Stats opt-in: {config.stats_opt_in}")
+        click.echo(f"  Phone home: {config.phone_home}")
+        td = config.token_discipline
+        click.echo(f"  Token soft cap: {td.soft_cap:,}")
+        click.echo(f"  Token ceiling: {td.ceiling:,}")
+
+
+def _set_config(calx_dir, config, key, value):
+    """Set a single config value."""
+    int_keys = {
+        "promotion_threshold": (1, 100),
+        "max_prompts_per_session": (1, 50),
+        "staleness_days": (1, 365),
+    }
+    if key in int_keys:
+        lo, hi = int_keys[key]
+        try:
+            parsed = int(value)
+        except ValueError:
+            click.echo(f"Invalid value for {key}: must be an integer", err=True)
+            return
+        if parsed < lo or parsed > hi:
+            click.echo(f"Invalid value for {key}: must be between {lo} and {hi}", err=True)
+            return
+        setattr(config, key, parsed)
+    elif key == "agent_naming":
+        if value not in ("self", "developer", "none"):
+            click.echo("Invalid value. Must be: self, developer, none", err=True)
+            return
+        config.agent_naming = value
+    elif key == "stats_opt_in":
+        config.stats_opt_in = value.lower() in ("true", "1", "yes")
+    elif key == "phone_home":
+        config.phone_home = value.lower() in ("true", "1", "yes")
+    else:
+        click.echo(f"Unknown config key: {key}", err=True)
+        return
+
+    save_config(calx_dir, config)
+    click.echo(f"Set {key} = {value}")

getcalx-0.1.0/src/calx/cli/correct.py

@@ -0,0 +1,69 @@
+"""calx correct — explicit correction capture."""
+from __future__ import annotations
+
+import json
+
+import click
+
+from calx.capture.explicit import capture_explicit
+from calx.core.config import find_calx_dir
+
+
+@click.command()
+@click.argument("message")
+@click.option("--domain", "-d", default=None, help="Override auto-detected domain")
+@click.option(
+    "--type",
+    "-t",
+    "correction_type",
+    default="process",
+    type=click.Choice(["process", "architectural"]),
+    help="Correction type",
+)
+@click.option("--context", "-c", default="", help="Additional context")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def correct(
+    message: str,
+    domain: str | None,
+    correction_type: str,
+    context: str,
+    as_json: bool,
+) -> None:
+    """Log a correction. Golden path: calx correct 'message'"""
+    calx_dir = find_calx_dir()
+    if not calx_dir:
+        click.echo("Not a Calx project. Run `calx init` first.", err=True)
+        raise SystemExit(1)
+
+    correction, feedback = capture_explicit(
+        calx_dir,
+        message,
+        domain=domain,
+        correction_type=correction_type,
+        context=context,
+    )
+
+    # Phone home — correct event (domain + type only, no content)
+    from calx.core.phone_home import send_event
+
+    send_event(calx_dir, "correct", {
+        "domain": correction.domain,
+        "correction_type": correction.type,
+    })
+
+    if as_json:
+        click.echo(
+            json.dumps(
+                {
+                    "id": correction.id,
+                    "domain": correction.domain,
+                    "type": correction.type,
+                    "description": correction.description,
+                    "status": correction.status,
+                    "feedback": feedback,
+                },
+                indent=2,
+            )
+        )
+    else:
+        click.echo(feedback)