clauderizer 0.2.0__py3-none-any.whl

clauderizer/__init__.py

@@ -0,0 +1,12 @@
+"""Clauderizer — drop-in, MCP-native working memory for AI agents.
+
+Markdown is the source of truth. Everything else (the graph index, the MCP
+server, the rituals) is derived from it and can be rebuilt at any time.
+"""
+
+__version__ = "0.2.0"
+
+# The version of the gameplan procedure this engine was built against. The
+# engine ships GAMEPLAN-PROCEDURE.md verbatim; `clauderize doctor` warns if a
+# host repo's procedure has drifted to a different MAJOR version.
+PROCEDURE_VERSION = "1.1.0"

clauderizer/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

clauderizer/assets.py

@@ -0,0 +1,43 @@
+"""Access to packaged template / profile / skill assets.
+
+Assets ship inside the wheel (see pyproject force-include). At runtime we read
+them straight off disk relative to this module — simple and import-light.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from string import Template
+
+_PKG = Path(__file__).parent
+TEMPLATES = _PKG / "templates"
+SKILLS = _PKG / "skills"
+
+
+def template_text(rel: str) -> str:
+    """Read a template by path relative to the templates dir."""
+    return (TEMPLATES / rel).read_text(encoding="utf-8")
+
+
+def render(rel: str, /, **vars: str) -> str:
+    """Read a ``$placeholder`` template and substitute ``vars``.
+
+    Uses ``safe_substitute`` so a stray ``$`` in a template never crashes a write.
+    """
+    return Template(template_text(rel)).safe_substitute(**vars)
+
+
+def doc_template(name: str) -> str | None:
+    """Template text for a named living doc (e.g. 'DECISIONS'), or None."""
+    p = TEMPLATES / "docs" / f"{name}.md"
+    return p.read_text(encoding="utf-8") if p.exists() else None
+
+
+def procedure_text() -> str:
+    return template_text("GAMEPLAN-PROCEDURE.md")
+
+
+def skill_dirs() -> list[Path]:
+    if not SKILLS.exists():
+        return []
+    return [d for d in sorted(SKILLS.iterdir()) if d.is_dir()]

clauderizer/cli.py

@@ -0,0 +1,256 @@
+"""``clauderize`` — the human/agent command line.
+
+Subcommands:
+    init      drop Clauderizer into the current repo (idempotent)
+    status    print the current gameplan digest
+    reindex   rebuild the disposable graph cache from markdown
+    doctor    verify the install and report drift
+    mcp       launch the MCP server (stdio)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+
+from . import PROCEDURE_VERSION, __version__
+from .config import Config
+from .graph import index
+from .paths import find_repo_root, resolve
+from .rituals import status_bundle
+from .scaffold.init import init as run_init
+from .tools_list import TOOL_NAMES
+
+
+def _load(root: Path | None = None):
+    paths = resolve(find_repo_root(root or Path.cwd()))
+    if not paths.config_file.exists():
+        return paths, None
+    return paths, Config.load(paths.config_file)
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    run_cmd = args.run_cmd.split() if args.run_cmd else None
+    report = run_init(
+        Path(args.path).resolve(),
+        size=args.size,
+        profile=args.profile,
+        gameplan=args.gameplan,
+        run_cmd=run_cmd,
+    )
+    print(f"Clauderized {report.repo}")
+    print(f"  size={report.size}  host profile={report.host_profile}")
+    n_changed = len(report.changed)
+    print(f"  {n_changed} file(s) written/updated, {len(report.actions) - n_changed} kept as-is")
+    if args.verbose:
+        for a in report.actions:
+            print(f"    {a}")
+    print("\nNext: open a Claude Code session here — the SessionStart hook will show status.")
+    print("Or run `clauderize status`.")
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    paths, config = _load()
+    if config is None:
+        print("Not a clauderized repo. Run `clauderize init`.")
+        return 1
+    bundle = status_bundle.compute(paths, config)
+    if args.json:
+        print(json.dumps(bundle, indent=2))
+    else:
+        print(status_bundle.render_digest(bundle, tools=TOOL_NAMES))
+    return 0
+
+
+def cmd_reindex(args: argparse.Namespace) -> int:
+    paths, config = _load()
+    if config is None:
+        print("Not a clauderized repo. Run `clauderize init`.")
+        return 1
+    graph = index.build(paths.docs)
+    index.write_cache(graph, paths.index_file, paths.docs)
+    print(f"Reindexed {len(graph.entities)} entities -> {paths.index_file}")
+    return 0
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    paths, config = _load()
+    if config is None:
+        print("✗ Not a clauderized repo (no .clauderizer/config.toml). Run `clauderize init`.")
+        return 1
+    ok = True
+
+    def check(label: str, condition: bool, detail: str = "") -> None:
+        nonlocal ok
+        mark = "✓" if condition else "✗"
+        print(f"{mark} {label}" + (f" — {detail}" if detail and not condition else ""))
+        if not condition:
+            ok = False
+
+    check("config.toml present", paths.config_file.exists())
+    check("procedure shipped", paths.procedure_file.exists())
+    check("CLAUDE.md stanza", _has_marker(paths.claude_md, "clauderizer"))
+    check(".mcp.json registers clauderizer", _mcp_registered(paths.mcp_json))
+    # Fidelity: registration present is not enough — the command must be launchable.
+    mcp_ok, mcp_detail = _command_runnable(_mcp_command(paths.mcp_json))
+    check("MCP server command runnable", mcp_ok, mcp_detail)
+    settings = paths.root / ".claude" / "settings.json"
+    check("SessionStart hook registered", _hook_registered(settings))
+    hook_ok, hook_detail = _command_runnable(_hook_command(settings))
+    check("SessionStart hook command runnable", hook_ok, hook_detail)
+    check("index cache present", paths.index_file.exists())
+    # procedure version drift (MAJOR)
+    drift = _procedure_drift(paths.procedure_file)
+    check("procedure version compatible", drift is None, drift or "")
+    if config.active_gameplan:
+        gp = paths.gameplan_dir(config.active_gameplan) / "GAMEPLAN.md"
+        check(f"active gameplan {config.active_gameplan} on disk", gp.exists())
+    print("\nOK" if ok else "\nDrift detected — re-run `clauderize init` to repair.")
+    return 0 if ok else 2
+
+
+def cmd_mcp(args: argparse.Namespace) -> int:
+    from .mcp_server import main as mcp_main
+
+    return mcp_main()
+
+
+# --- doctor helpers -----------------------------------------------------------
+
+
+def _has_marker(path: Path, name: str) -> bool:
+    if not path.exists():
+        return False
+    text = path.read_text(encoding="utf-8")
+    return f"<!-- {name}:start -->" in text
+
+
+def _mcp_registered(mcp_json: Path) -> bool:
+    if not mcp_json.exists():
+        return False
+    try:
+        data = json.loads(mcp_json.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return False
+    return "clauderizer" in data.get("mcpServers", {})
+
+
+def _hook_registered(settings: Path) -> bool:
+    if not settings.exists():
+        return False
+    try:
+        data = json.loads(settings.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return False
+    for group in data.get("hooks", {}).get("SessionStart", []):
+        for h in group.get("hooks", []):
+            if "clauderizer-hook" in h.get("command", ""):
+                return True
+    return False
+
+
+def _mcp_command(mcp_json: Path) -> list[str] | None:
+    if not mcp_json.exists():
+        return None
+    try:
+        data = json.loads(mcp_json.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return None
+    entry = data.get("mcpServers", {}).get("clauderizer")
+    if not entry:
+        return None
+    return [entry.get("command", ""), *entry.get("args", [])]
+
+
+def _hook_command(settings: Path) -> list[str] | None:
+    if not settings.exists():
+        return None
+    try:
+        data = json.loads(settings.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return None
+    for group in data.get("hooks", {}).get("SessionStart", []):
+        for h in group.get("hooks", []):
+            cmd = h.get("command", "")
+            if "clauderizer-hook" in cmd:
+                return cmd.split()
+    return None
+
+
+def _command_runnable(argv: list[str] | None) -> tuple[bool, str]:
+    """Can the configured launch command actually be executed on this machine?
+
+    Guards against a green health check on a setup that can't launch (e.g. a
+    ``.mcp.json`` pointing at ``uvx`` that isn't installed, or a dev path that
+    doesn't exist) — a check that's green while the server can't start is worse
+    than no check.
+    """
+    if not argv or not argv[0]:
+        return False, "no clauderizer command registered"
+    exe = argv[0]
+    if shutil.which(exe):
+        return True, exe
+    p = Path(exe)
+    if p.is_file() and os.access(p, os.X_OK):
+        return True, str(p)
+    return False, f"'{exe}' not found on PATH or not executable"
+
+
+def _procedure_drift(procedure_file: Path) -> str | None:
+    if not procedure_file.exists():
+        return "procedure file missing"
+    m = re.search(r"Procedure version\**:?\s*([0-9]+)\.([0-9]+)\.([0-9]+)",
+                  procedure_file.read_text(encoding="utf-8"))
+    if not m:
+        return None
+    host_major = int(m.group(1))
+    engine_major = int(PROCEDURE_VERSION.split(".")[0])
+    if host_major != engine_major:
+        return f"host procedure v{m.group(0)} vs engine v{PROCEDURE_VERSION} (MAJOR mismatch)"
+    return None
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="clauderize", description="Drop-in working memory for AI agents.")
+    p.add_argument("--version", action="version", version=f"clauderizer {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    pi = sub.add_parser("init", help="drop Clauderizer into this repo")
+    pi.add_argument("path", nargs="?", default=".", help="repo path (default: cwd)")
+    pi.add_argument("--size", choices=["pet", "standard", "saas"], default="standard")
+    pi.add_argument("--profile", default="auto", help="host language profile (default: auto-detect)")
+    pi.add_argument("--gameplan", default=None, help="also create a first gameplan with this name")
+    pi.add_argument("--run-cmd", default=None,
+                    help="how the repo invokes the engine (default: 'uvx --from clauderizer')")
+    pi.add_argument("-v", "--verbose", action="store_true")
+    pi.set_defaults(func=cmd_init)
+
+    ps = sub.add_parser("status", help="print current gameplan status")
+    ps.add_argument("--json", action="store_true")
+    ps.set_defaults(func=cmd_status)
+
+    pr = sub.add_parser("reindex", help="rebuild the graph cache from markdown")
+    pr.set_defaults(func=cmd_reindex)
+
+    pd = sub.add_parser("doctor", help="verify the install and report drift")
+    pd.set_defaults(func=cmd_doctor)
+
+    pm = sub.add_parser("mcp", help="launch the MCP server (stdio)")
+    pm.set_defaults(func=cmd_mcp)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv if argv is not None else sys.argv[1:])
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

clauderizer/config.py

@@ -0,0 +1,175 @@
+"""Load and write ``.clauderizer/config.toml`` — the size/profile dial.
+
+Reading uses stdlib ``tomllib``. Writing uses a tiny emitter (stdlib has no
+TOML writer) that covers exactly the shapes we store: tables of strings, bools,
+and lists of strings. Keeping the config in TOML avoids YAML's ambiguity for
+machine-edited settings; frontmatter inside docs stays YAML per the procedure.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+CONFIG_VERSION = "1"
+
+# Default module/ritual manifests per size. Mirrors the procedure's sizing
+# matrix, but as a real dial instead of prose advice.
+SIZE_MANIFESTS: dict[str, dict[str, Any]] = {
+    "pet": {
+        "modules": ["VISION"],
+        "rituals": {"preflight": True, "cascade": False, "amendments": False},
+        "preflight_checks": ["clean_tree", "tests"],
+    },
+    "standard": {
+        "modules": [
+            "VISION",
+            "ARCHITECTURE",
+            "DECISIONS",
+            "INVARIANTS",
+            "TESTING",
+            "HARDENING",
+        ],
+        "rituals": {"preflight": True, "cascade": True, "amendments": False},
+        "preflight_checks": [
+            "branch_base",
+            "clean_tree",
+            "tests",
+            "build",
+            "deps_spotcheck",
+            "branch_creation",
+            "cascade_hygiene",
+        ],
+    },
+    "saas": {
+        "modules": [
+            "VISION",
+            "REQUIREMENTS",
+            "ARCHITECTURE",
+            "ENGINEERING-PRINCIPLES",
+            "DEPLOYMENT",
+            "DATASOURCES",
+            "SCHEMA",
+            "SECURITY",
+            "TESTING",
+            "HARDENING",
+            "INCIDENTS",
+            "DECISIONS",
+            "INVARIANTS",
+            "GLOSSARY",
+        ],
+        "rituals": {"preflight": True, "cascade": True, "amendments": True},
+        "preflight_checks": [
+            "branch_base",
+            "clean_tree",
+            "tests",
+            "build",
+            "deps_spotcheck",
+            "branch_creation",
+            "cascade_hygiene",
+        ],
+    },
+}
+
+
+@dataclass
+class Config:
+    version: str = CONFIG_VERSION
+    size: str = "standard"
+    host_profile: str = "generic"
+    docs: str = "docs"
+    gameplans: str = "docs/gameplans"
+    modules: list[str] = field(default_factory=list)
+    rituals: dict[str, bool] = field(default_factory=dict)
+    preflight_checks: list[str] = field(default_factory=list)
+    active_gameplan: str | None = None
+
+    @classmethod
+    def for_size(cls, size: str, host_profile: str = "generic") -> "Config":
+        manifest = SIZE_MANIFESTS.get(size, SIZE_MANIFESTS["standard"])
+        return cls(
+            size=size,
+            host_profile=host_profile,
+            modules=list(manifest["modules"]),
+            rituals=dict(manifest["rituals"]),
+            preflight_checks=list(manifest["preflight_checks"]),
+        )
+
+    def ritual_enabled(self, name: str) -> bool:
+        return bool(self.rituals.get(name, False))
+
+    @classmethod
+    def load(cls, path: Path) -> "Config":
+        with path.open("rb") as fh:
+            raw = tomllib.load(fh)
+        cz = raw.get("clauderizer", {})
+        host = raw.get("host", {})
+        paths = raw.get("paths", {})
+        modules = raw.get("modules", {})
+        rituals = raw.get("rituals", {})
+        active = raw.get("active_gameplan", {})
+        return cls(
+            version=str(cz.get("version", CONFIG_VERSION)),
+            size=str(cz.get("size", "standard")),
+            host_profile=str(host.get("profile", "generic")),
+            docs=str(paths.get("docs", "docs")),
+            gameplans=str(paths.get("gameplans", "docs/gameplans")),
+            modules=list(modules.get("enabled", [])),
+            rituals={k: bool(v) for k, v in rituals.items()},
+            preflight_checks=list(cz.get("preflight_checks", [])),
+            active_gameplan=(active.get("id") or None),
+        )
+
+    def to_toml(self) -> str:
+        lines = [
+            "[clauderizer]",
+            f'version = "{self.version}"',
+            f'size = "{self.size}"',
+            _toml_kv("preflight_checks", self.preflight_checks),
+            "",
+            "[host]",
+            f'profile = "{self.host_profile}"',
+            "",
+            "[paths]",
+            f'docs = "{self.docs}"',
+            f'gameplans = "{self.gameplans}"',
+            "",
+            "[modules]",
+            _toml_kv("enabled", self.modules),
+            "",
+            "[rituals]",
+        ]
+        for k, v in self.rituals.items():
+            lines.append(f"{k} = {'true' if v else 'false'}")
+        lines += ["", "[active_gameplan]", f'id = "{self.active_gameplan or ""}"', ""]
+        return "\n".join(lines)
+
+
+def _toml_kv(key: str, value: Any) -> str:
+    if isinstance(value, list):
+        inner = ", ".join(f'"{v}"' for v in value)
+        return f"{key} = [{inner}]"
+    if isinstance(value, bool):
+        return f"{key} = {'true' if value else 'false'}"
+    return f'{key} = "{value}"'
+
+
+def merge_missing(existing: Config, defaults: Config) -> Config:
+    """Return ``existing`` with any empty fields filled from ``defaults``.
+
+    Used by ``init`` re-runs so user edits are never overwritten — only gaps are
+    filled in.
+    """
+    return Config(
+        version=existing.version or defaults.version,
+        size=existing.size or defaults.size,
+        host_profile=existing.host_profile or defaults.host_profile,
+        docs=existing.docs or defaults.docs,
+        gameplans=existing.gameplans or defaults.gameplans,
+        modules=existing.modules or defaults.modules,
+        rituals=existing.rituals or defaults.rituals,
+        preflight_checks=existing.preflight_checks or defaults.preflight_checks,
+        active_gameplan=existing.active_gameplan or defaults.active_gameplan,
+    )

clauderizer/graph/__init__.py

@@ -0,0 +1,9 @@
+"""The Project DAG: a graph of frontmatter-tracked entities.
+
+- ``index`` scans the docs tree into an in-memory graph (cached to index.json).
+- ``query`` answers lookup / dependents / dependencies / pin-violation questions.
+- ``cascade`` does the post-hoc forward walk and renders a cascade report.
+
+The cache is never authoritative. If it is stale or missing it is rebuilt from
+the markdown — markdown always wins.
+"""

clauderizer/graph/cascade.py

@@ -0,0 +1,127 @@
+"""Post-hoc cascade: walk the DAG forward after a change, render a report.
+
+Per the procedure, cascade is *judgment-based*: this engine finds and reports
+the dependents that *might* be affected and marks each "needs review". It does
+not pretend to decide whether each dependent is truly affected — that's the
+agent's call, filled into the report. This is the deliberate division of labor
+that keeps cascade honest rather than faking automation.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import query
+from .index import Graph
+
+
+def render_report(
+    graph: Graph,
+    entity_id: str,
+    transition: str,
+    *,
+    now: datetime | None = None,
+    phase: str | None = None,
+) -> str:
+    now = now or datetime.now(timezone.utc)
+    ts = now.strftime("%Y-%m-%dT%H:%M:%SZ")
+    direct = query.dependents(graph, entity_id)
+    transitive = [d for d in query.transitive_dependents(graph, entity_id) if d not in direct]
+    violations = [v for v in query.pin_violations(graph) if v.target == entity_id]
+
+    lines = [
+        f"# Cascade Report: {entity_id} {transition}",
+        "",
+        f"> Generated: {ts}",
+    ]
+    if phase:
+        lines.append(f"> Phase: {phase}")
+    lines += [
+        "",
+        "## Trigger",
+        "",
+        f"`{entity_id}` — {transition}",
+        "",
+        "## Affected entities",
+        "",
+        "### Direct dependents",
+        "",
+    ]
+    if direct:
+        for d in direct:
+            ent = graph.get(d)
+            status = ent.status if ent else "?"
+            lines.append(f"- **{d}** (status: {status}) — checked: _needs review_")
+    else:
+        lines.append("- _(none)_")
+    lines += ["", "### Transitive dependents", ""]
+    if transitive:
+        for d in transitive:
+            lines.append(f"- **{d}** — flagged via upstream; checked: _needs review_")
+    else:
+        lines.append("- _(none)_")
+
+    if violations:
+        lines += ["", "### Semver pin violations", ""]
+        for v in violations:
+            lines.append(f"- **{v.dependent}** pins `{v.constraint}` — {v.reason}")
+
+    lines += [
+        "",
+        "## Updates applied",
+        "",
+        "_(fill in concrete edits made to each affected entity, or 'no change needed')_",
+        "",
+        "## Updates deferred",
+        "",
+        "_(anything flagged but not yet acted on, with reason + follow-up)_",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def report_filename(entity_id: str, now: datetime | None = None) -> str:
+    now = now or datetime.now(timezone.utc)
+    safe = entity_id.replace("/", "-").replace(" ", "-")
+    return f"{now.strftime('%Y-%m-%d')}-{safe}.md"
+
+
+def run(
+    graph: Graph,
+    entity_id: str,
+    transition: str,
+    reports_dir: Path,
+    *,
+    dry_run: bool = False,
+    now: datetime | None = None,
+    phase: str | None = None,
+) -> dict:
+    """Render and (unless ``dry_run``) write a cascade report.
+
+    Returns a structured result describing what was found and where it went.
+    """
+    now = now or datetime.now(timezone.utc)
+    report_md = render_report(graph, entity_id, transition, now=now, phase=phase)
+    direct = query.dependents(graph, entity_id)
+    transitive = [d for d in query.transitive_dependents(graph, entity_id) if d not in direct]
+    path = reports_dir / report_filename(entity_id, now)
+    written = False
+    if not dry_run:
+        reports_dir.mkdir(parents=True, exist_ok=True)
+        path.write_text(report_md, encoding="utf-8")
+        written = True
+    return {
+        "ok": True,
+        "entity_id": entity_id,
+        "transition": transition,
+        "direct": direct,
+        "transitive": transitive,
+        "report_md": report_md,
+        "report_path": str(path),
+        "written": written,
+        "summary": (
+            f"cascade {entity_id} {transition}: "
+            f"{len(direct)} direct, {len(transitive)} transitive dependents"
+        ),
+    }