@grifhinz/logics-manager 2.0.0

package/logics_manager/bootstrap.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .assist import _build_claude_bridge_manifest, _build_claude_instructions
+
+
+WORKFLOW_DIRS: tuple[str, ...] = ("request", "backlog", "tasks", "specs", "product", "architecture", "external", ".cache")
+
+
+def _workflow_directories(repo_root: Path) -> list[Path]:
+    return [repo_root / "logics" / name for name in WORKFLOW_DIRS]
+
+
+def bootstrap_payload(repo_root: Path, *, check: bool) -> dict[str, object]:
+    logics_root = repo_root / "logics"
+    bridge_manifest = _build_claude_bridge_manifest(repo_root)
+    instructions_manifest = _build_claude_instructions(repo_root)
+    directory_actions: list[dict[str, object]] = []
+    created_paths: list[str] = []
+    missing_paths: list[str] = []
+
+    if not logics_root.exists():
+        missing_paths.append("logics/")
+    elif not logics_root.is_dir():
+        raise SystemExit(f"`{logics_root}` exists but is not a directory.")
+
+    if not check and not logics_root.exists():
+        logics_root.mkdir(parents=True, exist_ok=True)
+        created_paths.append("logics/")
+
+    for directory in _workflow_directories(repo_root):
+        relative = directory.relative_to(repo_root).as_posix()
+        needs_create = not directory.exists()
+        needs_gitkeep = (
+            True
+            if not directory.exists()
+            else directory.is_dir()
+            and not any(entry.is_file() for entry in directory.iterdir())
+            and not (directory / ".gitkeep").exists()
+        )
+        directory_actions.append({"path": relative, "exists": directory.exists(), "needs_gitkeep": needs_gitkeep})
+        if needs_create:
+            missing_paths.append(relative + "/")
+            if not check:
+                directory.mkdir(parents=True, exist_ok=True)
+                created_paths.append(relative + "/")
+                gitkeep = directory / ".gitkeep"
+                if not gitkeep.exists():
+                    gitkeep.write_text("", encoding="utf-8")
+                    created_paths.append(f"{relative}/.gitkeep")
+        elif needs_gitkeep:
+            missing_paths.append(f"{relative}/.gitkeep")
+            if not check:
+                (directory / ".gitkeep").write_text("", encoding="utf-8")
+                created_paths.append(f"{relative}/.gitkeep")
+
+    instructions_path = logics_root / "instructions.md"
+    instructions_content = str(instructions_manifest["content"])
+    instructions_missing = not instructions_path.exists()
+    instructions_stale = False
+    if not instructions_missing:
+        try:
+            instructions_stale = instructions_path.read_text(encoding="utf-8") != instructions_content
+        except Exception:
+            instructions_stale = True
+    if instructions_missing or instructions_stale:
+        missing_paths.append("logics/instructions.md")
+        if not check:
+            instructions_path.write_text(instructions_content, encoding="utf-8")
+            created_paths.append("logics/instructions.md")
+
+    for bridge in bridge_manifest["bridges"]:
+        for rel_path, content in (
+            (str(bridge["command_path"]), str(bridge["command_content"])),
+            (str(bridge["agent_path"]), str(bridge["agent_content"])),
+        ):
+            bridge_path = repo_root / rel_path
+            if bridge_path.exists():
+                try:
+                    if bridge_path.read_text(encoding="utf-8") == content:
+                        continue
+                except Exception:
+                    pass
+            missing_paths.append(rel_path)
+            if not check:
+                bridge_path.parent.mkdir(parents=True, exist_ok=True)
+                bridge_path.write_text(content, encoding="utf-8")
+                created_paths.append(rel_path)
+
+    ok = not missing_paths if check else True
+    return {
+        "command": "bootstrap",
+        "repo_root": repo_root.as_posix(),
+        "check": check,
+        "ok": ok,
+        "missing_paths": missing_paths,
+        "created_paths": created_paths,
+        "directory_actions": directory_actions,
+        "claude_bridge_count": bridge_manifest["bridge_count"],
+        "claude_instruction_line_count": instructions_manifest["line_count"],
+    }
+
+
+def render_bootstrap(payload: dict[str, object], *, output_format: str) -> str:
+    if output_format == "json":
+        return json.dumps(payload, indent=2, sort_keys=True)
+    if payload["check"]:
+        if payload["ok"]:
+            return "Bootstrap check: OK"
+        lines = ["Bootstrap check: actions required"]
+        for path in payload["missing_paths"]:
+            lines.append(f"- missing: {path}")
+        return "\n".join(lines)
+    lines = ["Bootstrap: OK"]
+    if payload["created_paths"]:
+        lines.append("- created:")
+        for path in payload["created_paths"]:
+            lines.append(f"  - {path}")
+    else:
+        lines.append("- nothing to create")
+    return "\n".join(lines)

package/logics_manager/cli.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import argparse
+from importlib import metadata
+import sys
+from pathlib import Path
+from textwrap import dedent
+
+from .bootstrap import bootstrap_payload, render_bootstrap
+from .assist import main as assist_main
+from .audit import audit_payload, build_parser as build_audit_parser
+from .audit import render_audit
+from .config import ConfigError, find_repo_root, render_config_show
+from .index import index_payload, render_index
+from .lint import lint_payload, render_lint
+from .doctor import render_doctor
+
+
+def get_cli_version() -> str:
+    version_file = Path(__file__).resolve().parents[1] / "VERSION"
+    try:
+        version = version_file.read_text(encoding="utf-8").strip()
+    except OSError:
+        version = ""
+    if version:
+        return version
+
+    try:
+        return metadata.version("logics-manager")
+    except metadata.PackageNotFoundError:
+        pass
+    return "0.0.0"
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    parser = argparse.ArgumentParser(
+        prog="logics-manager",
+        description="Canonical Logics CLI for workflow, validation, and runtime operations.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=dedent(
+            """
+            Examples:
+              logics-manager flow new request --title "My request"
+              logics-manager audit
+              logics-manager config show --format json
+            """
+        ).strip(),
+    )
+    parser.add_argument("--version", action="version", version=f"logics-manager {get_cli_version()}")
+    parser.add_argument(
+        "command",
+        nargs="?",
+        choices=("bootstrap", "flow", "sync", "assist", "audit", "index", "lint", "config", "doctor"),
+    )
+    parser.add_argument("rest", nargs=argparse.REMAINDER)
+    args = parser.parse_args(argv[:1])
+
+    if args.command is None:
+        parser.print_help()
+        return 1
+
+    rest = argv[1:]
+    if args.command == "config":
+        if not rest or rest[0] != "show":
+            raise SystemExit("Usage: logics-manager config show [args...]")
+        config_args = rest[1:]
+        parser = argparse.ArgumentParser(prog="logics-manager config show", add_help=False)
+        parser.add_argument("--format", choices=("text", "json"), default="text")
+        parsed, _unknown = parser.parse_known_args(config_args)
+        repo_root = find_repo_root(Path.cwd())
+        try:
+            output = render_config_show(repo_root, output_format=parsed.format)
+        except ConfigError as exc:
+            raise SystemExit(str(exc)) from exc
+        print(output)
+        return 0
+    if args.command == "doctor":
+        doctor_args = rest
+        parser = argparse.ArgumentParser(prog="logics-manager doctor", add_help=False)
+        parser.add_argument("--format", choices=("text", "json"), default="text")
+        parsed, _unknown = parser.parse_known_args(doctor_args)
+        repo_root = find_repo_root(Path.cwd())
+        try:
+            output = render_doctor(repo_root, output_format=parsed.format)
+        except ConfigError as exc:
+            raise SystemExit(str(exc)) from exc
+        print(output)
+        return 0
+    if args.command == "bootstrap":
+        parser = argparse.ArgumentParser(prog="logics-manager bootstrap", add_help=False)
+        parser.add_argument("--check", action="store_true")
+        parser.add_argument("--format", choices=("text", "json"), default="text")
+        parsed, _unknown = parser.parse_known_args(rest)
+        try:
+            repo_root = find_repo_root(Path.cwd())
+        except ConfigError:
+            repo_root = Path.cwd().resolve()
+        payload = bootstrap_payload(repo_root, check=parsed.check)
+        print(render_bootstrap(payload, output_format=parsed.format))
+        return 0 if payload["ok"] else 1
+    if args.command == "flow" and rest[:1] in (["new"], ["companion"], ["promote"], ["split"], ["close"], ["finish"]):
+        from .flow import main as flow_main
+
+        return flow_main(rest)
+    if args.command == "sync":
+        if rest[:1] not in (["close-eligible-requests"], ["refresh-mermaid-signatures"], ["schema-status"], ["context-pack"], ["export-graph"]):
+            raise SystemExit("Unsupported sync subcommand for the native CLI slice.")
+        from .sync import main as sync_main
+
+        return sync_main(rest)
+    if args.command == "assist":
+        if rest[:1] not in (["runtime-status"], ["diff-risk"], ["commit-plan"], ["changed-surface-summary"], ["doc-consistency"], ["review-checklist"], ["validation-checklist"], ["validation-summary"], ["test-impact-summary"], ["roi-report"], ["next-step"], ["claude-bridges"], ["claude-instructions"], ["request-draft"], ["spec-first-pass"], ["backlog-groom"], ["closure-summary"], ["context"]):
+            raise SystemExit("Unsupported assist subcommand for the native CLI slice.")
+        return assist_main(rest)
+    if args.command == "audit":
+        audit_parser = build_audit_parser()
+        parsed, _unknown = audit_parser.parse_known_args(rest)
+        repo_root = find_repo_root(Path.cwd())
+        try:
+            payload = audit_payload(
+                repo_root,
+                stale_days=parsed.stale_days,
+                skip_ac_traceability=parsed.skip_ac_traceability,
+                skip_gates=parsed.skip_gates,
+                legacy_cutoff_version=parsed.legacy_cutoff_version,
+                group_by_doc=parsed.group_by_doc,
+                autofix_ac_traceability=parsed.autofix_ac_traceability,
+                paths=parsed.paths,
+                refs=parsed.refs,
+                since_version=parsed.since_version,
+                token_hygiene=parsed.token_hygiene,
+                autofix_structure=parsed.autofix_structure,
+                governance_profile=parsed.governance_profile,
+            )
+            output = render_audit(
+                repo_root,
+                stale_days=parsed.stale_days,
+                skip_ac_traceability=parsed.skip_ac_traceability,
+                skip_gates=parsed.skip_gates,
+                legacy_cutoff_version=parsed.legacy_cutoff_version,
+                output_format=parsed.format,
+                group_by_doc=parsed.group_by_doc,
+                autofix_ac_traceability=parsed.autofix_ac_traceability,
+                paths=parsed.paths,
+                refs=parsed.refs,
+                since_version=parsed.since_version,
+                token_hygiene=parsed.token_hygiene,
+                autofix_structure=parsed.autofix_structure,
+                governance_profile=parsed.governance_profile,
+            )
+        except ConfigError as exc:
+            raise SystemExit(str(exc)) from exc
+        print(output)
+        return 0 if payload["ok"] else 1
+    if args.command == "index":
+        parser = argparse.ArgumentParser(prog="logics-manager index", add_help=False)
+        parser.add_argument("--out", default="logics/INDEX.md")
+        parser.add_argument("--format", choices=("text", "json"), default="text")
+        parsed, _unknown = parser.parse_known_args(rest)
+        repo_root = find_repo_root(Path.cwd())
+        try:
+            payload = index_payload(repo_root, out=parsed.out)
+        except ConfigError as exc:
+            raise SystemExit(str(exc)) from exc
+        output = render_index(repo_root, out=parsed.out, output_format=parsed.format) if parsed.format == "json" else f"Wrote {payload['output_path']}"
+        print(output)
+        return 0 if payload["ok"] else 1
+    if args.command == "lint":
+        parser = argparse.ArgumentParser(prog="logics-manager lint", add_help=False)
+        parser.add_argument("--require-status", action="store_true")
+        parser.add_argument("--format", choices=("text", "json"), default="text")
+        parsed, _unknown = parser.parse_known_args(rest)
+        repo_root = find_repo_root(Path.cwd())
+        try:
+            payload = lint_payload(repo_root, require_status=parsed.require_status)
+            output = render_lint(repo_root, require_status=parsed.require_status, output_format=parsed.format)
+        except ConfigError as exc:
+            raise SystemExit(str(exc)) from exc
+        print(output)
+        return 0 if payload["ok"] else 1
+    raise SystemExit(f"Unsupported command: {args.command}")

package/logics_manager/config.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_LOGICS_CONFIG: dict[str, Any] = {
+    "version": 1,
+    "workflow": {
+        "split": {
+            "policy": "minimal-coherent",
+            "max_children_without_override": 4,
+        }
+    },
+    "mutations": {
+        "mode": "transactional",
+        "audit_log": "logics/mutation_audit.jsonl",
+    },
+    "index": {
+        "enabled": True,
+        "path": "logics/.cache/runtime_index.json",
+    },
+    "hybrid_assist": {
+        "default_backend": "auto",
+        "next_step_auto_backend": None,
+        "default_model_profile": "deepseek-coder",
+        "default_model": "deepseek-coder-v2:16b",
+        "env_file": ".env",
+        "result_cache": {
+            "enabled": True,
+            "path": "logics/.cache/flow_results_cache.json",
+            "ttl_seconds": 600,
+        },
+        "model_profiles": {
+            "deepseek-coder": {
+                "family": "deepseek",
+                "model": "deepseek-coder-v2:16b",
+                "description": "DeepSeek Coder V2 profile for shared local coding and hybrid assist work.",
+                "example_tags": ["deepseek-coder-v2:16b", "deepseek-coder-v2:latest"],
+            },
+            "qwen-coder": {
+                "family": "qwen",
+                "model": "qwen2.5-coder:14b",
+                "description": "Qwen coder profile for bounded local coding and hybrid assist work.",
+                "example_tags": ["qwen2.5-coder:14b", "qwen2.5-coder:7b"],
+            },
+        },
+        "ollama_host": "http://127.0.0.1:11434",
+        "timeout_seconds": 20.0,
+        "audit_log": "logics/.cache/hybrid_assist_audit.jsonl",
+        "measurement_log": "logics/.cache/hybrid_assist_measurements.jsonl",
+        "provider_health_path": "logics/.cache/provider_health.json",
+        "providers": {
+            "readiness_cooldown_seconds": 300,
+            "ollama": {
+                "enabled": True,
+                "host": "http://127.0.0.1:11434",
+            },
+            "openai": {
+                "enabled": False,
+                "base_url": "https://api.openai.com/v1",
+                "model": "gpt-4.1-mini",
+                "api_key_env": "OPENAI_API_KEY",
+            },
+            "gemini": {
+                "enabled": False,
+                "base_url": "https://generativelanguage.googleapis.com/v1beta",
+                "model": "gemini-2.0-flash",
+                "api_key_env": "GEMINI_API_KEY",
+            },
+        },
+    },
+}
+
+
+class ConfigError(SystemExit):
+    pass
+
+
+def _strip_comment(value: str) -> str:
+    stripped = value.strip()
+    if not stripped.startswith(('"', "'")) and "#" in stripped:
+        stripped = stripped.split("#", 1)[0].rstrip()
+    return stripped
+
+
+def _coerce_scalar(value: str) -> Any:
+    stripped = _strip_comment(value)
+    if stripped in {"", "null", "Null", "NULL", "~"}:
+        return None
+    if stripped in {"true", "True"}:
+        return True
+    if stripped in {"false", "False"}:
+        return False
+    if stripped.startswith(("'", '"')) and stripped.endswith(("'", '"')) and len(stripped) >= 2:
+        return stripped[1:-1]
+    try:
+        return int(stripped)
+    except ValueError:
+        pass
+    try:
+        return float(stripped)
+    except ValueError:
+        pass
+    return stripped
+
+
+def _prepared_lines(text: str) -> list[tuple[int, str]]:
+    prepared: list[tuple[int, str]] = []
+    for raw in text.splitlines():
+        if not raw.strip():
+            continue
+        stripped = raw.lstrip(" ")
+        if stripped.startswith("#"):
+            continue
+        indent = len(raw) - len(stripped)
+        prepared.append((indent, stripped.rstrip()))
+    return prepared
+
+
+def _parse_block(lines: list[tuple[int, str]], index: int, indent: int) -> tuple[Any, int]:
+    if index >= len(lines):
+        return {}, index
+    current_indent, content = lines[index]
+    if current_indent < indent:
+        return {}, index
+
+    if content.startswith("- "):
+        items: list[Any] = []
+        while index < len(lines):
+            current_indent, content = lines[index]
+            if current_indent < indent:
+                break
+            if current_indent != indent or not content.startswith("- "):
+                raise ConfigError(f"Invalid list indentation in logics.yaml near `{content}`.")
+            item_content = content[2:].strip()
+            index += 1
+            if not item_content:
+                if index < len(lines) and lines[index][0] > indent:
+                    nested_indent = lines[index][0]
+                    value, index = _parse_block(lines, index, nested_indent)
+                else:
+                    value = None
+            elif ":" in item_content and not item_content.startswith(("'", '"')) and not item_content.endswith(":"):
+                key, raw_value = item_content.split(":", 1)
+                value = {key.strip(): _coerce_scalar(raw_value.strip())}
+            elif item_content.endswith(":") and not item_content.startswith(("'", '"')):
+                key = item_content[:-1].strip()
+                if index < len(lines) and lines[index][0] > indent:
+                    nested_indent = lines[index][0]
+                    nested_value, index = _parse_block(lines, index, nested_indent)
+                else:
+                    nested_value = {}
+                value = {key: nested_value}
+            else:
+                value = _coerce_scalar(item_content)
+            items.append(value)
+        return items, index
+
+    mapping: dict[str, Any] = {}
+    while index < len(lines):
+        current_indent, content = lines[index]
+        if current_indent < indent:
+            break
+        if current_indent != indent:
+            raise ConfigError(f"Invalid mapping indentation in logics.yaml near `{content}`.")
+        if ":" not in content:
+            raise ConfigError(f"Expected `key: value` in logics.yaml, got `{content}`.")
+        key, raw_value = content.split(":", 1)
+        key = key.strip()
+        raw_value = raw_value.strip()
+        index += 1
+        if raw_value:
+            mapping[key] = _coerce_scalar(raw_value)
+            continue
+        if index < len(lines) and lines[index][0] > current_indent:
+            nested_indent = lines[index][0]
+            value, index = _parse_block(lines, index, nested_indent)
+        else:
+            value = {}
+        mapping[key] = value
+    return mapping, index
+
+
+def parse_simple_yaml(text: str) -> dict[str, Any]:
+    lines = _prepared_lines(text)
+    if not lines:
+        return {}
+    parsed, index = _parse_block(lines, 0, lines[0][0])
+    if index != len(lines):
+        raise ConfigError("Could not parse the full logics.yaml payload.")
+    if not isinstance(parsed, dict):
+        raise ConfigError("logics.yaml must decode to a top-level mapping.")
+    return parsed
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    merged = deepcopy(base)
+    for key, value in override.items():
+        current = merged.get(key)
+        if isinstance(current, dict) and isinstance(value, dict):
+            merged[key] = _deep_merge(current, value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def find_repo_root(start: Path) -> Path:
+    current = start.resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / "logics").is_dir():
+            return candidate
+    raise ConfigError("Could not locate repo root (missing 'logics/' directory). Run from inside the repo.")
+
+
+def config_path(repo_root: Path) -> Path:
+    return repo_root / "logics.yaml"
+
+
+def load_repo_config(repo_root: Path) -> tuple[dict[str, Any], Path | None]:
+    path = config_path(repo_root)
+    if not path.is_file():
+        return deepcopy(DEFAULT_LOGICS_CONFIG), None
+    try:
+        override = parse_simple_yaml(path.read_text(encoding="utf-8"))
+    except ConfigError:
+        raise
+    except Exception as exc:
+        raise ConfigError(f"Failed to parse {path.relative_to(repo_root)}: {exc}") from exc
+    return _deep_merge(DEFAULT_LOGICS_CONFIG, override), path
+
+
+def render_config_show(repo_root: Path, *, output_format: str = "text") -> str:
+    config, path = load_repo_config(repo_root)
+    payload = {
+        "config_path": str(path.relative_to(repo_root)) if path is not None else None,
+        "config": config,
+    }
+    if output_format == "json":
+        return json.dumps(payload, indent=2, sort_keys=True)
+
+    lines = [
+        f"Config source: {payload['config_path'] or '<defaults>'}",
+        f"Version: {config.get('version', 'unknown')}",
+        f"Workflow split policy: {config.get('workflow', {}).get('split', {}).get('policy', 'unknown')}",
+        f"Default backend: {config.get('hybrid_assist', {}).get('default_backend', 'unknown')}",
+        f"Default model: {config.get('hybrid_assist', {}).get('default_model', 'unknown')}",
+    ]
+    return "\n".join(lines)

package/logics_manager/doctor.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .config import ConfigError, load_repo_config
+
+
+REQUIRED_DIRECTORIES = ("logics/request", "logics/backlog", "logics/tasks")
+SCHEMA_VERSION_PATTERN = re.compile(r"^\s*>\s*Schema version:\s*(.+?)\s*$", re.MULTILINE)
+
+
+@dataclass(frozen=True)
+class DoctorIssue:
+    code: str
+    path: str
+    message: str
+    remediation: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "code": self.code,
+            "path": self.path,
+            "message": self.message,
+            "remediation": self.remediation,
+        }
+
+
+def _check_required_directories(repo_root: Path) -> list[DoctorIssue]:
+    issues: list[DoctorIssue] = []
+    for relative in REQUIRED_DIRECTORIES:
+        candidate = repo_root / relative
+        if candidate.is_dir():
+            continue
+        issues.append(
+            DoctorIssue(
+                code="missing_directory",
+                path=relative,
+                message=f"Missing required directory `{relative}`.",
+                remediation=f"Create `{relative}` or bootstrap the Logics workflow corpus.",
+            )
+        )
+    return issues
+
+
+def _check_schema_versions(repo_root: Path) -> list[DoctorIssue]:
+    issues: list[DoctorIssue] = []
+    for directory in REQUIRED_DIRECTORIES:
+        candidate_dir = repo_root / directory
+        if not candidate_dir.is_dir():
+            continue
+        for doc_path in sorted(candidate_dir.glob("*.md")):
+            try:
+                text = doc_path.read_text(encoding="utf-8")
+            except Exception as exc:  # pragma: no cover - defensive filesystem guard
+                issues.append(
+                    DoctorIssue(
+                        code="unreadable_doc",
+                        path=doc_path.relative_to(repo_root).as_posix(),
+                        message=f"Could not read workflow doc: {exc}",
+                        remediation="Fix the file permissions or remove the broken file.",
+                    )
+                )
+                continue
+            if SCHEMA_VERSION_PATTERN.search(text):
+                continue
+            issues.append(
+                DoctorIssue(
+                    code="missing_schema_version",
+                    path=doc_path.relative_to(repo_root).as_posix(),
+                    message="Workflow doc is missing a schema version indicator.",
+                    remediation="Add `> Schema version: 1.0` near the top of the document.",
+                )
+            )
+    return issues
+
+
+def doctor_payload(repo_root: Path) -> dict[str, Any]:
+    issues: list[DoctorIssue] = []
+    issues.extend(_check_required_directories(repo_root))
+
+    config_path = None
+    try:
+        _config, config_path = load_repo_config(repo_root)
+    except ConfigError as exc:
+        issues.append(
+            DoctorIssue(
+                code="invalid_config",
+                path="logics.yaml",
+                message=str(exc),
+                remediation="Fix `logics.yaml` so the runtime config can be parsed.",
+            )
+        )
+
+    issues.extend(_check_schema_versions(repo_root))
+    payload = {
+        "ok": not issues,
+        "issue_count": len(issues),
+        "issues": [issue.to_dict() for issue in issues],
+        "config_path": str(config_path.relative_to(repo_root)) if config_path is not None else None,
+        "workflow_doc_count": sum(1 for directory in REQUIRED_DIRECTORIES for _ in (repo_root / directory).glob("*.md") if (repo_root / directory).is_dir()),
+        "missing_schema_version_count": sum(1 for issue in issues if issue.code == "missing_schema_version"),
+    }
+    return payload
+
+
+def render_doctor(repo_root: Path, *, output_format: str = "text") -> str:
+    payload = doctor_payload(repo_root)
+    if output_format == "json":
+        return json.dumps(payload, indent=2, sort_keys=True)
+
+    lines = [
+        "Logics doctor: OK" if payload["ok"] else "Logics doctor: FAILED",
+        f"Workflow docs inspected: {payload['workflow_doc_count']}",
+    ]
+    if payload["issues"]:
+        max_issues = 10
+        for issue in payload["issues"][:max_issues]:
+            lines.append(f"- [{issue['code']}] {issue['path']}: {issue['message']}")
+            lines.append(f"  remediation: {issue['remediation']}")
+        remaining = len(payload["issues"]) - max_issues
+        if remaining > 0:
+            lines.append(f"... and {remaining} more issue(s).")
+    return "\n".join(lines)