coding-os 0.3.2__py3-none-any.whl

scripts/dev/migrate_check_ids.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ID_MAP: dict[str, str] = {
+    "C1": "config.file_present",
+    "C2": "state.directory_present",
+    "C3": "database.openable",
+    "C4": "database.schema_current",
+    "C5": "database.tables_present",
+    "C6": "scaffold.roots_present",
+    "C7": "adapter.configured",
+    "C8": "scaffold.manifest_fresh",
+    "C9": "scaffold.placeholders_resolved",
+    "C10": "mcp.self_test_passes",
+    "C11": "stack.registry_valid",
+    "C12": "stack.category_balance",
+    "C13": "stack.skills_linked",
+    "C14": "mcp.portable",
+    "C15": "mcp.actually_launches",
+    "C16": "docs.agents_md_present",
+    "C17": "graph.freshness",
+    "C18": "graph.parse_error_rate",
+    "C19": "graph.backend_responsive",
+    "C20": "graph.groups_configured",
+    "C21": "graph.embedding_migration",
+    "C22": "graph.embedding_dimensions",
+    "C23": "graph.cascade_overflow",
+    # C24 graph.kuzu_state — retired 2026-05-18 with the Kuzu backend.
+    "C25": "graph.evidence_table",
+    "C26": "graph.orphan_symbols",
+    "C27": "graph.legacy_kinds",
+    "C28": "cognition.registries_present",
+    "C29": "hook.coverage",
+    "C30": "scheduled.cron_configured",
+    "C31": "presence.no_zombies",
+    "C32": "runtime.optional_extras_installed",
+    "C33": "adapter.all_installed_healthy",
+    "C34": "hub.http_responsive",
+    "C35": "docs.markdown_link_integrity",
+    "C36": "graph.uid_consistency",
+    "C37": "scaffold.regen_artifacts_fresh",
+    "C38": "board.config_yamls_valid",
+    "C39": "hub.project_paths_exist",
+    "C40": "state.size_within_budget",
+    "C41": "mcp.dispatcher_modules_importable",
+    "C42": "mcp.envelope_contract_sample",
+    "C43": "runtime.cli_binary_health",
+    "C44": "scaffold.boundary_yamls_valid",
+    "C45": "adapter.identity_file_present",
+    "C46": "adapter.symlinks_healthy",
+    "C47": "hub.consumer_hook_symlinks_healthy",
+    "C48": "hook.cos_env_sourced",
+    "C50": "board.wip_within_caps",
+    "C51": "board.no_stale_tasks",
+    "C52": "board.frontmatter_valid",
+    "C53": "board.index_synced",
+}
+
+CHECK_CALL = re.compile(
+    r'((?:CheckResult|_CR)\(\s*)"(C\d+)"\s*,\s*"([a-z_]+)"',
+    flags=re.DOTALL,
+)
+
+# Standalone "C\d+" literal in tests + comments — only rewritten in test files.
+ID_LITERAL = re.compile(r'"(C\d+)"')
+
+# Bare C-id reference in docstrings / comments (word-boundary, no surrounding quotes).
+BARE_REF = re.compile(r"\bC(\d+)\b")
+
+
+def rewrite(text: str, path: Path) -> tuple[str, int]:
+    replacements = 0
+
+    def sub(match: re.Match) -> str:
+        nonlocal replacements
+        prefix, old_id, _slug = match.group(1), match.group(2), match.group(3)
+        new_id = ID_MAP.get(old_id)
+        if new_id is None:
+            print(f"  WARN: unmapped id {old_id} in {path}", file=sys.stderr)
+            return match.group(0)
+        replacements += 1
+        return f'{prefix}"{new_id}"'
+
+    return CHECK_CALL.sub(sub, text), replacements
+
+
+def rewrite_literals(text: str) -> tuple[str, int]:
+    replacements = 0
+
+    def sub(match: re.Match) -> str:
+        nonlocal replacements
+        old_id = match.group(1)
+        new_id = ID_MAP.get(old_id)
+        if new_id is None:
+            return match.group(0)
+        replacements += 1
+        return f'"{new_id}"'
+
+    return ID_LITERAL.sub(sub, text), replacements
+
+
+def rewrite_bare_refs(text: str) -> tuple[str, int]:
+    replacements = 0
+
+    def sub(match: re.Match) -> str:
+        nonlocal replacements
+        old_id = f"C{match.group(1)}"
+        new_id = ID_MAP.get(old_id)
+        if new_id is None:
+            return match.group(0)
+        replacements += 1
+        return new_id
+
+    return BARE_REF.sub(sub, text), replacements
+
+
+def main() -> int:
+    targets = [
+        Path("src/cli/doctor.py"),
+        Path("src/cli/doctor_graph.py"),
+        Path("src/cli/doctor_extras.py"),
+        Path("src/cli/doctor_board.py"),
+    ]
+    test_targets = [
+        Path("tests/test_doctor.py"),
+        Path("tests/test_hooks_phase_f.py"),
+        Path("tests/test_persona_integration.py"),
+    ]
+    total = 0
+    for path in targets:
+        if not path.exists():
+            print(f"missing: {path}", file=sys.stderr)
+            continue
+        original = path.read_text(encoding="utf-8")
+        rewritten, count = rewrite(original, path)
+        if count == 0:
+            print(f"  {path}: no matches")
+            continue
+        path.write_text(rewritten, encoding="utf-8")
+        print(f"  {path}: {count} rewritten")
+        total += count
+    for path in test_targets:
+        if not path.exists():
+            print(f"missing: {path}", file=sys.stderr)
+            continue
+        original = path.read_text(encoding="utf-8")
+        rewritten, count = rewrite_literals(original)
+        if count == 0:
+            print(f"  {path}: no test literals matched")
+            continue
+        path.write_text(rewritten, encoding="utf-8")
+        print(f"  {path}: {count} literals rewritten")
+        total += count
+    for path in targets:
+        original = path.read_text(encoding="utf-8")
+        rewritten, count = rewrite_bare_refs(original)
+        if count == 0:
+            continue
+        path.write_text(rewritten, encoding="utf-8")
+        print(f"  {path}: {count} bare refs rewritten")
+        total += count
+    print(f"total replacements: {total}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/dev/strip_purpose_blocks.py

@@ -0,0 +1,154 @@
+"""Strip legacy PURPOSE/INPUT/OUTPUT/DEPENDENCIES/NOTES docstring blocks.
+
+Per AGENTS.md Rule 12 (rewritten 2026-05-05).
+Usage: python scripts/dev/strip_purpose_blocks.py [--apply]
+"""
+
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+TARGET_DIRS = ["core", "cli", "adapters", "scripts", "tests"]
+EXCLUDE_DIRS = {"__pycache__", ".coding-os", "node_modules", ".venv", "dist", "build"}
+SECTION_KEYWORDS = ("PURPOSE:", "INPUT:", "OUTPUT:", "DEPENDENCIES:", "NOTES:")
+
+
+def _iter_py_files() -> list[Path]:
+    files: list[Path] = []
+    for d in TARGET_DIRS:
+        for p in (ROOT / d).rglob("*.py"):
+            if any(part in EXCLUDE_DIRS for part in p.parts):
+                continue
+            files.append(p)
+    return files
+
+
+def _strip_purpose(text: str) -> str | None:
+    if "PURPOSE:" not in text:
+        return None
+    lines = text.splitlines()
+    keep: list[str] = []
+    in_section = False
+    section_indent: int | None = None
+
+    for ln in lines:
+        stripped = ln.lstrip()
+        starts_section = any(stripped.startswith(kw) for kw in SECTION_KEYWORDS)
+
+        if starts_section:
+            in_section = True
+            section_indent = len(ln) - len(stripped)
+            continue
+
+        if in_section:
+            if not stripped:
+                continue
+            cur_indent = len(ln) - len(stripped)
+            if section_indent is not None and cur_indent > section_indent:
+                continue
+            in_section = False
+            section_indent = None
+
+        keep.append(ln)
+
+    while keep and not keep[0].strip():
+        keep.pop(0)
+    while keep and not keep[-1].strip():
+        keep.pop()
+
+    return "\n".join(keep)
+
+
+def _process_file(path: Path) -> tuple[int, int, str]:
+    src = path.read_text(encoding="utf-8")
+    if "PURPOSE:" not in src:
+        return (0, 0, src)
+    try:
+        tree = ast.parse(src)
+    except SyntaxError:
+        return (0, 0, src)
+
+    src_lines = src.splitlines(keepends=True)
+    edits: list[tuple[int, int, str]] = []
+    modified = 0
+    removed = 0
+
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            continue
+        body = getattr(node, "body", None)
+        if not body:
+            continue
+        first = body[0]
+        if not isinstance(first, ast.Expr):
+            continue
+        if not isinstance(first.value, ast.Constant) or not isinstance(first.value.value, str):
+            continue
+
+        new_text = _strip_purpose(first.value.value)
+        if new_text is None:
+            continue
+
+        start_line = first.lineno - 1
+        end_line = first.end_lineno
+
+        if not new_text.strip():
+            siblings = [s for s in body if s is not first]
+            if not siblings and isinstance(
+                node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+            ):
+                indent = " " * first.col_offset
+                edits.append((start_line, end_line, f"{indent}pass\n"))
+            else:
+                edits.append((start_line, end_line, ""))
+            removed += 1
+        else:
+            indent = " " * first.col_offset
+            if "\n" in new_text:
+                rebuilt = f'{indent}"""{new_text}\n{indent}"""\n'
+            else:
+                rebuilt = f'{indent}"""{new_text}"""\n'
+            edits.append((start_line, end_line, rebuilt))
+            modified += 1
+
+    if not edits:
+        return (0, 0, src)
+
+    edits.sort(key=lambda e: e[0], reverse=True)
+    for start, end, replacement in edits:
+        src_lines[start:end] = [replacement] if replacement else []
+
+    return (modified, removed, "".join(src_lines))
+
+
+def main(apply: bool) -> int:
+    total_files = 0
+    total_modified = 0
+    total_removed = 0
+
+    for path in _iter_py_files():
+        modified, removed, new_src = _process_file(path)
+        if modified == 0 and removed == 0:
+            continue
+        total_files += 1
+        total_modified += modified
+        total_removed += removed
+        if apply:
+            path.write_text(new_src, encoding="utf-8")
+            print(f"  rewrote {path.relative_to(ROOT)}: {modified} stripped, {removed} removed")
+
+    mode = "APPLIED" if apply else "DRY RUN"
+    print(f"\n{mode}")
+    print(f"  files affected:        {total_files}")
+    print(f"  PURPOSE blocks stripped (summary kept):     {total_modified}")
+    print(f"  docstrings removed entirely (PURPOSE-only): {total_removed}")
+    if not apply and total_files:
+        print("\n  rerun with --apply to write changes")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(apply="--apply" in sys.argv))

scripts/dump_openapi.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Dump the Hub FastAPI OpenAPI spec to docs/api/openapi.json.
+
+The Hub's HTTP contract is otherwise only visible at runtime
+(`GET /openapi.json` while `cos hub start` is running). Snapshotting
+it into the repo gives offline consumers a stable contract file and
+lets CI diff-guard against accidental API drift.
+
+Usage:
+    python3 src/scripts/dump_openapi.py            # write the snapshot
+    python3 src/scripts/dump_openapi.py --check    # fail if drifted
+
+Exit: 0 on success / in-sync; 1 on drift (--check); 2 on error.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+SNAPSHOT = REPO_ROOT / "docs" / "api" / "openapi.json"
+
+
+def _build_spec() -> dict:
+    # Import lazily so a missing `web` extra produces a clean message.
+    sys.path.insert(0, str(REPO_ROOT / "src" / "core"))
+    try:
+        from web.server import create_app
+    except Exception as exc:  # pragma: no cover - import-time failure
+        print(f"FAIL: cannot import the Hub app: {exc}", file=sys.stderr)
+        raise SystemExit(2) from exc
+    app = create_app()
+    return app.openapi()
+
+
+def main(argv: list[str]) -> int:
+    check_only = "--check" in argv[1:]
+    spec = _build_spec()
+    # Stable, deterministic serialization (sorted keys, 2-space indent).
+    rendered = json.dumps(spec, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+
+    if check_only:
+        if not SNAPSHOT.exists():
+            print(f"FAIL: snapshot missing: {SNAPSHOT}", file=sys.stderr)
+            return 1
+        current = SNAPSHOT.read_text(encoding="utf-8")
+        if current != rendered:
+            print(
+                "FAIL: OpenAPI spec drifted from docs/api/openapi.json.\n"
+                "      Run: python3 src/scripts/dump_openapi.py",
+                file=sys.stderr,
+            )
+            return 1
+        print("OK: OpenAPI snapshot is in sync.")
+        return 0
+
+    SNAPSHOT.parent.mkdir(parents=True, exist_ok=True)
+    SNAPSHOT.write_text(rendered, encoding="utf-8")
+    print(f"wrote {SNAPSHOT.relative_to(REPO_ROOT)} ({len(rendered)} bytes)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

scripts/e2e_dispatch_tool.py

@@ -0,0 +1,195 @@
+"""
+End-to-end test for cos_dispatch_formula_run and cos_dispatch_parallel_run.
+
+Verifies the full path:
+  MCP tool call → dispatcher factory → claude-agent-sdk → real Claude Code →
+  ```json``` block → EvidenceBundle persistence → formula_dispatches row.
+
+Run: uv run --extra claude-sdk python scripts/e2e_dispatch_tool.py
+
+NOTE: Spawns real Claude Code sub-sessions. Expect ~30-60s total.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent.parent
+sys.path.insert(0, str(ROOT / "src" / "core" / "thinking_os"))
+
+# Isolate E2E state under a sandbox dir so we don't pollute real session files
+SANDBOX = ROOT / ".coding-os" / "e2e-sdk-test"
+SANDBOX.mkdir(parents=True, exist_ok=True)
+os.environ["COS_AGENT"] = "claude"
+os.environ["COS_AGENT_DIR"] = str(SANDBOX)
+
+# Redirect evidence bundle to sandbox
+SESSION_ID = f"ses-claude-e2e-{int(time.time())}"
+TASK_MARKER = "e2e-dispatch-sdk-test"
+PERSONA_ID = "senior-backend"
+
+# Import after env setup
+from tools.cognition import (
+    _load_bundle,
+    register_cos_dispatch_formula_run,
+    register_cos_dispatch_parallel_run,
+)
+
+
+class FakeMCP:
+    """Minimal fake matching the @mcp.tool(name=…) decorator shape."""
+
+    def __init__(self):
+        self.tools = {}
+
+    def tool(self, name, description="", **kw):
+        def deco(fn):
+            self.tools[name] = fn
+            return fn
+
+        return deco
+
+
+def run_single(mcp, db_path) -> dict:
+    print("\n=== Single-formula dispatch (F7 — debug) ===")
+    fn = mcp.tools["cos_dispatch_formula_run"]
+    t0 = time.monotonic()
+    raw = fn(
+        formula_id="debugger",
+        session_id=SESSION_ID,
+        task_marker=TASK_MARKER,
+        persona_id=PERSONA_ID,
+        intensity="light",
+        timeout_s=90.0,
+    )
+    wall_ms = int((time.monotonic() - t0) * 1000)
+    envelope = json.loads(raw) if isinstance(raw, str) else raw
+    print(f"  envelope.ok: {envelope.get('ok')}")
+    data = envelope.get("data", {})
+    print(f"  status: {data.get('status')}")
+    print(f"  dispatcher: {data.get('dispatcher_name')}")
+    print(f"  latency_ms: {data.get('latency_ms')}")
+    print(f"  output keys: {sorted(list(data.get('output_json', {}).keys()))[:6]}")
+    print(f"  bundle_fields_filled: {data.get('bundle_fields_filled')}")
+    print(f"  wall_ms: {wall_ms}")
+    return {"envelope": envelope, "wall_ms": wall_ms}
+
+
+def run_parallel(mcp, db_path) -> dict:
+    print("\n=== Parallel dispatch (F5+F7 concurrent) ===")
+    fn = mcp.tools["cos_dispatch_parallel_run"]
+    t0 = time.monotonic()
+    raw = fn(
+        formula_ids=["implementer", "debugger"],
+        session_id=SESSION_ID,
+        task_marker=TASK_MARKER + "-par",
+        persona_id=PERSONA_ID,
+        intensity="light",
+        timeout_s=90.0,
+    )
+    wall_ms = int((time.monotonic() - t0) * 1000)
+    envelope = json.loads(raw) if isinstance(raw, str) else raw
+    data = envelope.get("data", {})
+    print(f"  envelope.ok: {envelope.get('ok')}")
+    print(f"  ok_count: {data.get('ok_count')}/{data.get('total')}")
+    print(f"  parallel_wall_ms: {data.get('parallel_wall_ms')}")
+    print(f"  total wall_ms (inc. serialization): {wall_ms}")
+    for r in data.get("results", []):
+        print(
+            f"    → {r['formula_id']}: status={r['status']} "
+            f"latency={r['latency_ms']}ms fields_filled={r['bundle_fields_filled']}"
+        )
+    return {"envelope": envelope, "wall_ms": wall_ms}
+
+
+def verify_bundle():
+    print("\n=== Bundle persistence check ===")
+    bundle = _load_bundle(SESSION_ID, TASK_MARKER, PERSONA_ID)
+    filled = []
+    for attr in (
+        "researcher",
+        "analyst",
+        "architect",
+        "documenter",
+        "implementer",
+        "reviewer",
+        "debugger",
+        "security_auditor",
+        "deployer",
+        "observer",
+        "refactorer",
+    ):
+        if getattr(bundle, attr, None) is not None:
+            filled.append(attr)
+    print(f"  populated fields: {filled}")
+    return filled
+
+
+def verify_db_row(db_path):
+    print("\n=== DB audit row check (formula_dispatches) ===")
+    with sqlite3.connect(db_path) as conn:
+        rows = conn.execute(
+            "SELECT formula_id, status, latency_ms "
+            "FROM formula_dispatches WHERE session_id=? ORDER BY rowid DESC LIMIT 10",
+            (SESSION_ID,),
+        ).fetchall()
+    for r in rows:
+        print(f"  {r}")
+    return rows
+
+
+def main():
+    from database import DEFAULT_DB_PATH
+
+    db_path = str(DEFAULT_DB_PATH)
+
+    mcp = FakeMCP()
+    register_cos_dispatch_formula_run(mcp, db_path)
+    register_cos_dispatch_parallel_run(mcp, db_path)
+    print(f"registered tools: {list(mcp.tools.keys())}")
+
+    single = run_single(mcp, db_path)
+    parallel = run_parallel(mcp, db_path)
+    filled = verify_bundle()
+    rows = verify_db_row(db_path)
+
+    print("\n=== E2E Summary ===", file=sys.stderr)
+    single_ok = (
+        single["envelope"].get("ok") is True and single["envelope"]["data"].get("status") == "ok"
+    )
+    parallel_ok = (
+        parallel["envelope"].get("ok") is True
+        and parallel["envelope"]["data"].get("ok_count", 0) >= 1
+    )
+    bundle_ok = "debugger" in filled and "implementer" in filled
+    db_ok = len(rows) >= 2
+    print(f"  single dispatch:    {'✓' if single_ok else '✗'}", file=sys.stderr)
+    print(f"  parallel dispatch:  {'✓' if parallel_ok else '✗'}", file=sys.stderr)
+    print(f"  bundle persisted:   {'✓' if bundle_ok else '✗'} ({filled})", file=sys.stderr)
+    print(f"  DB audit row:       {'✓' if db_ok else '✗'} ({len(rows)} rows)", file=sys.stderr)
+    ok = single_ok and parallel_ok and bundle_ok and db_ok
+    print(f"\nE2E: {'PASS' if ok else 'FAIL'}", file=sys.stderr)
+    # Machine-readable verdict on stdout (the result a caller scrapes).
+    print(
+        json.dumps(
+            {
+                "result": "pass" if ok else "fail",
+                "single_ok": single_ok,
+                "parallel_ok": parallel_ok,
+                "bundle_ok": bundle_ok,
+                "db_ok": db_ok,
+                "populated_fields": filled,
+                "db_rows": len(rows),
+            }
+        )
+    )
+    return 0 if ok else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())