@grifhinz/logics-manager 2.1.2 → 2.3.0

package/logics_manager/flow_evidence.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from datetime import date
+import re
+
+
+def section_lines(lines: list[str], heading: str) -> list[str]:
+    start_idx = None
+    target = heading.strip().lower()
+    for idx, line in enumerate(lines):
+        if line.startswith("# ") and line[2:].strip().lower() == target:
+            start_idx = idx + 1
+            break
+    if start_idx is None:
+        return []
+    out: list[str] = []
+    for idx in range(start_idx, len(lines)):
+        line = lines[idx]
+        if line.startswith("# "):
+            break
+        out.append(line)
+    return out
+
+
+def has_validation_evidence(text: str) -> bool:
+    concrete_ok_context = ("lint", "audit", "test", "pytest", "npm", "ci", "coverage", "smoke", "package")
+    invalid_markers = ("...", "todo", "tbd", "pending", "needs ", "need ", "not ok", "failed", "failure", "failing")
+    for line in section_lines(text.splitlines(), "Validation"):
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        value = stripped[2:].strip().lower()
+        if not value or value.startswith("run `") or value.startswith("run the "):
+            continue
+        if any(marker in value for marker in invalid_markers):
+            continue
+        if "command:" in value and "result:" in value and ("date:" in value or "session:" in value):
+            result_match = re.search(r"\bresult:\s*([^|,;]+)", value)
+            result = result_match.group(1).strip() if result_match else ""
+            if result in {"pass", "passed", "ok", "success", "succeeded"}:
+                return True
+        if any(marker in value for marker in ("pass", "validated", "verified", "verification", "regression")):
+            return True
+        if "ok" in value and any(marker in value for marker in concrete_ok_context):
+            return True
+    return False
+
+
+def has_ac_proof(text: str, ac_id: str) -> bool:
+    upper = text.upper()
+    return ac_id.upper() in upper and "proof:" in text.lower()
+
+
+def structured_validation_line(command: str, result: str, note: str | None) -> str:
+    normalized_result = result.strip().lower() or "passed"
+    parts = [
+        f"command: `{command.strip()}`",
+        f"result: {normalized_result}",
+        f"date: {date.today().isoformat()}",
+    ]
+    if note and note.strip():
+        parts.append(f"note: {note.strip()}")
+    return " | ".join(parts)

package/logics_manager/index.py

@@ -8,6 +8,7 @@ from os import path as os_path
 from pathlib import Path
 
 from .config import find_repo_root
+from .path_utils import resolve_repo_output_path
 
 
 @dataclass(frozen=True)
@@ -91,7 +92,7 @@ def index_payload(repo_root: Path, *, out: str = "logics/INDEX.md") -> dict[str,
     for title, rel_dir, show_progress in SECTION_DEFINITIONS:
         sections.append((title, _collect_entries(repo_root, rel_dir), show_progress))
 
-    out_path = (repo_root / out).resolve()
+    out_path, output_path = resolve_repo_output_path(repo_root, out)
     out_dir = out_path.parent
     content = "\n".join(
         [
@@ -104,15 +105,10 @@ def index_payload(repo_root: Path, *, out: str = "logics/INDEX.md") -> dict[str,
     out_path.parent.mkdir(parents=True, exist_ok=True)
     out_path.write_text(content, encoding="utf-8")
 
-    try:
-        printable = out_path.relative_to(repo_root)
-    except ValueError:
-        printable = out_path
-
     counts = {key: len(entries) for key, (_, entries, _) in zip(SECTION_COUNT_KEYS, sections)}
     return {
         "ok": True,
-        "output_path": printable.as_posix(),
+        "output_path": output_path,
         "counts": counts,
     }
 

package/logics_manager/insights.py

@@ -0,0 +1,418 @@
+from __future__ import annotations
+
+import json
+import re
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+
+
+WORKFLOW_KINDS = ("request", "backlog", "task")
+COMPANION_KINDS = ("product", "architecture")
+OPEN_STATUSES = {"Draft", "Ready", "In progress", "Blocked"}
+CLOSED_STATUSES = {"Done", "Archived"}
+
+
+@dataclass(frozen=True)
+class LogicsDoc:
+    kind: str
+    path: Path
+    rel_path: str
+    ref: str
+    title: str
+    status: str | None
+    progress: int | None
+    content: str
+
+
+def _doc_dirs(repo_root: Path) -> dict[str, Path]:
+    return {
+        "request": repo_root / "logics" / "request",
+        "backlog": repo_root / "logics" / "backlog",
+        "task": repo_root / "logics" / "tasks",
+        "product": repo_root / "logics" / "product",
+        "architecture": repo_root / "logics" / "architecture",
+    }
+
+
+def _progress_value(raw: str | None) -> int | None:
+    if raw is None:
+        return None
+    match = re.search(r"(\d+)", raw)
+    if not match:
+        return None
+    return max(0, min(100, int(match.group(1))))
+
+
+def _parse_doc(repo_root: Path, kind: str, path: Path) -> LogicsDoc:
+    content = path.read_text(encoding="utf-8")
+    title = "(missing title)"
+    status: str | None = None
+    progress: int | None = None
+    for line in content.splitlines():
+        if line.startswith("## "):
+            heading = line.removeprefix("## ").strip()
+            if " - " in heading:
+                _, title = heading.split(" - ", 1)
+            else:
+                title = heading
+            continue
+        if line.startswith("> Status:"):
+            status = line.split(":", 1)[1].strip()
+            continue
+        if line.startswith("> Progress:"):
+            progress = _progress_value(line.split(":", 1)[1].strip())
+            continue
+    return LogicsDoc(
+        kind=kind,
+        path=path,
+        rel_path=path.relative_to(repo_root).as_posix(),
+        ref=path.stem,
+        title=title,
+        status=status,
+        progress=progress,
+        content=content,
+    )
+
+
+def collect_logics_docs(repo_root: Path, *, kinds: tuple[str, ...] = WORKFLOW_KINDS + COMPANION_KINDS) -> list[LogicsDoc]:
+    docs: list[LogicsDoc] = []
+    for kind, directory in _doc_dirs(repo_root).items():
+        if kind not in kinds or not directory.is_dir():
+            continue
+        for path in sorted(directory.glob("*.md")):
+            docs.append(_parse_doc(repo_root, kind, path))
+    return docs
+
+
+def _status_counts(docs: list[LogicsDoc]) -> dict[str, dict[str, int]]:
+    counts: dict[str, dict[str, int]] = {}
+    for doc in docs:
+        status = doc.status or "(missing)"
+        counts.setdefault(doc.kind, {})
+        counts[doc.kind][status] = counts[doc.kind].get(status, 0) + 1
+    return counts
+
+
+def _doc_summary(doc: LogicsDoc) -> dict[str, object]:
+    return {
+        "ref": doc.ref,
+        "title": doc.title,
+        "kind": doc.kind,
+        "status": doc.status,
+        "progress": doc.progress,
+        "path": doc.rel_path,
+    }
+
+
+def status_payload(repo_root: Path, *, limit: int = 10) -> dict[str, object]:
+    docs = collect_logics_docs(repo_root, kinds=WORKFLOW_KINDS)
+    open_docs = [doc for doc in docs if doc.status not in CLOSED_STATUSES]
+    active_tasks = [
+        doc
+        for doc in open_docs
+        if doc.kind == "task" and doc.status in {"Ready", "In progress", "Blocked"}
+    ]
+    ready_backlog = [
+        doc
+        for doc in open_docs
+        if doc.kind == "backlog" and doc.status in {"Ready", "In progress", "Blocked"}
+    ]
+    task_text = "\n".join(doc.content for doc in docs if doc.kind == "task")
+    backlog_without_task = [doc for doc in ready_backlog if doc.ref not in task_text]
+    draft_requests = [doc for doc in open_docs if doc.kind == "request" and doc.status == "Draft"]
+    blocked_docs = [doc for doc in open_docs if doc.status == "Blocked"]
+
+    next_actions: list[str] = []
+    if blocked_docs:
+        next_actions.append(f"Review {len(blocked_docs)} blocked doc(s).")
+    if active_tasks:
+        next_actions.append(f"Continue or finish {len(active_tasks)} active task(s).")
+    if backlog_without_task:
+        next_actions.append(f"Promote {len(backlog_without_task)} ready backlog item(s) without detected task links.")
+    if draft_requests:
+        next_actions.append(f"Groom {len(draft_requests)} draft request(s).")
+    if not next_actions:
+        next_actions.append("No open workflow action detected.")
+
+    return {
+        "ok": True,
+        "counts": _status_counts(docs),
+        "open_count": len(open_docs),
+        "active_tasks": [_doc_summary(doc) for doc in active_tasks[:limit]],
+        "backlog_without_task": [_doc_summary(doc) for doc in backlog_without_task[:limit]],
+        "draft_requests": [_doc_summary(doc) for doc in draft_requests[:limit]],
+        "blocked_docs": [_doc_summary(doc) for doc in blocked_docs[:limit]],
+        "next_actions": next_actions,
+    }
+
+
+def render_status(repo_root: Path, *, output_format: str = "text", limit: int = 10) -> str:
+    payload = status_payload(repo_root, limit=limit)
+    if output_format == "json":
+        return json.dumps(payload, indent=2, sort_keys=True)
+
+    lines = [
+        "Logics status:",
+        f"- open workflow docs: {payload['open_count']}",
+        "- next actions:",
+    ]
+    lines.extend(f"  - {action}" for action in payload["next_actions"])
+    for key, label in (
+        ("active_tasks", "Active tasks"),
+        ("backlog_without_task", "Backlog without detected task"),
+        ("draft_requests", "Draft requests"),
+        ("blocked_docs", "Blocked docs"),
+    ):
+        items = payload[key]
+        if not items:
+            continue
+        lines.append(f"- {label}:")
+        for item in items:
+            lines.append(f"  - {item['ref']} [{item['status']}]: {item['title']}")
+    return "\n".join(lines)
+
+
+def health_payload(repo_root: Path, *, limit: int = 10) -> dict[str, object]:
+    docs = collect_logics_docs(repo_root, kinds=WORKFLOW_KINDS + COMPANION_KINDS)
+    workflow_docs = [doc for doc in docs if doc.kind in WORKFLOW_KINDS]
+    missing_status = [doc for doc in docs if not doc.status]
+    done_without_full_progress = [
+        doc for doc in workflow_docs if doc.status == "Done" and doc.kind in {"backlog", "task"} and doc.progress != 100
+    ]
+    complete_progress_not_done = [
+        doc for doc in workflow_docs if doc.progress == 100 and doc.status not in CLOSED_STATUSES
+    ]
+    blocked_docs = [doc for doc in workflow_docs if doc.status == "Blocked"]
+    open_docs = [doc for doc in workflow_docs if doc.status not in CLOSED_STATUSES]
+
+    task_text = "\n".join(doc.content for doc in workflow_docs if doc.kind == "task")
+    backlog_without_task = [
+        doc
+        for doc in open_docs
+        if doc.kind == "backlog" and doc.status in {"Ready", "In progress", "Blocked"} and doc.ref not in task_text
+    ]
+
+    issue_groups = {
+        "missing_status": missing_status,
+        "done_without_full_progress": done_without_full_progress,
+        "complete_progress_not_done": complete_progress_not_done,
+        "blocked_docs": blocked_docs,
+        "backlog_without_task": backlog_without_task,
+    }
+    issue_count = sum(len(items) for items in issue_groups.values())
+    return {
+        "ok": issue_count == 0,
+        "doc_count": len(docs),
+        "workflow_doc_count": len(workflow_docs),
+        "open_workflow_count": len(open_docs),
+        "counts": _status_counts(docs),
+        "issue_count": issue_count,
+        "issues": {key: [_doc_summary(doc) for doc in items[:limit]] for key, items in issue_groups.items()},
+    }
+
+
+def render_health(repo_root: Path, *, output_format: str = "text", limit: int = 10) -> str:
+    payload = health_payload(repo_root, limit=limit)
+    if output_format == "json":
+        return json.dumps(payload, indent=2, sort_keys=True)
+
+    lines = [
+        "Logics health:",
+        f"- docs: {payload['doc_count']}",
+        f"- workflow docs: {payload['workflow_doc_count']}",
+        f"- open workflow docs: {payload['open_workflow_count']}",
+        f"- issue signals: {payload['issue_count']}",
+    ]
+    issues = payload["issues"]
+    for key, items in issues.items():
+        if not items:
+            continue
+        label = key.replace("_", " ")
+        lines.append(f"- {label}:")
+        for item in items:
+            lines.append(f"  - {item['ref']} [{item['status']}]: {item['title']}")
+    return "\n".join(lines)
+
+
+def _slug_command_title(text: str) -> str:
+    cleaned = re.sub(r"`([^`]+)`", r"\1", text)
+    cleaned = re.sub(r"[*_]+", "", cleaned)
+    cleaned = re.sub(r"\s+", " ", cleaned.strip(" .:-"))
+    if len(cleaned) > 96:
+        cleaned = cleaned[:93].rstrip(" ,.;:") + "..."
+    return cleaned[:1].upper() + cleaned[1:] if cleaned else "Follow up"
+
+
+def _is_actionable_followup(text: str) -> bool:
+    normalized = re.sub(r"\s+", " ", text.strip(" .")).lower()
+    if normalized in {"none", "n/a", "not needed", "no follow-up"}:
+        return False
+    if normalized.startswith("no ") and "follow-up" in normalized:
+        return False
+    if normalized.startswith("no ") and "is required" in normalized:
+        return False
+    if "no new adr is required" in normalized:
+        return False
+    if "no new architecture decision" in normalized:
+        return False
+    return True
+
+
+def followups_payload(
+    repo_root: Path,
+    *,
+    limit: int = 50,
+    source_kind: str = "all",
+    include_closed: bool = False,
+    closed_only: bool = False,
+) -> dict[str, object]:
+    docs = collect_logics_docs(repo_root, kinds=WORKFLOW_KINDS + COMPANION_KINDS)
+    if source_kind != "all":
+        docs = [doc for doc in docs if doc.kind == source_kind]
+    if closed_only:
+        docs = [doc for doc in docs if doc.status in CLOSED_STATUSES]
+    elif not include_closed:
+        docs = [doc for doc in docs if doc.status not in CLOSED_STATUSES]
+    followups: list[dict[str, object]] = []
+    patterns = ("Follow-up area:", "Product follow-up:", "Architecture follow-up:")
+    for doc in docs:
+        for index, line in enumerate(doc.content.splitlines(), start=1):
+            stripped = line.strip().lstrip("- ").strip()
+            matched = next((pattern for pattern in patterns if stripped.startswith(pattern)), None)
+            if not matched:
+                continue
+            text = stripped.removeprefix(matched).strip()
+            if not _is_actionable_followup(text):
+                continue
+            title = _slug_command_title(text)
+            quoted_title = shlex.quote(title)
+            followups.append(
+                {
+                    "source_ref": doc.ref,
+                    "source_path": doc.rel_path,
+                    "source_kind": doc.kind,
+                    "line": index,
+                    "text": text,
+                    "suggested_title": title,
+                    "suggested_command": f"python3 -m logics_manager flow new request --title {quoted_title}",
+                }
+            )
+    return {
+        "ok": True,
+        "count": len(followups),
+        "returned_count": min(len(followups), limit),
+        "filters": {
+            "source_kind": source_kind,
+            "include_closed": include_closed,
+            "closed_only": closed_only,
+        },
+        "followups": followups[:limit],
+    }
+
+
+def render_followups(
+    repo_root: Path,
+    *,
+    output_format: str = "text",
+    limit: int = 50,
+    source_kind: str = "all",
+    include_closed: bool = False,
+    closed_only: bool = False,
+) -> str:
+    payload = followups_payload(
+        repo_root,
+        limit=limit,
+        source_kind=source_kind,
+        include_closed=include_closed,
+        closed_only=closed_only,
+    )
+    if output_format == "json":
+        return json.dumps(payload, indent=2, sort_keys=True)
+
+    lines = [f"Logics follow-ups: {payload['count']} found"]
+    for item in payload["followups"]:
+        lines.append(f"- {item['source_ref']}:{item['line']} {item['text']}")
+        lines.append(f"  command: {item['suggested_command']}")
+    return "\n".join(lines)
+
+
+def _related_ref(content: str, label: str) -> str | None:
+    prefix = f"> Related {label}:"
+    for line in content.splitlines():
+        if not line.startswith(prefix):
+            continue
+        value = line.split(":", 1)[1].strip()
+        normalized = value.strip("`").strip().lower()
+        if not normalized or normalized.startswith("(none"):
+            return None
+        match = re.search(r"`([^`]+)`", value)
+        return match.group(1) if match else value
+    return None
+
+
+def product_consistency_payload(repo_root: Path, *, limit: int = 50) -> dict[str, object]:
+    docs = collect_logics_docs(repo_root, kinds=WORKFLOW_KINDS + COMPANION_KINDS)
+    docs_by_ref = {doc.ref: doc for doc in docs}
+    product_docs = [doc for doc in docs if doc.kind == "product"]
+    checked_product_docs = [doc for doc in product_docs if doc.status != "Proposed"]
+    issues: list[dict[str, object]] = []
+    expected = {
+        "request": "request",
+        "backlog": "backlog",
+        "task": "task",
+    }
+    for doc in checked_product_docs:
+        missing_related: list[str] = []
+        broken_related: list[dict[str, str]] = []
+        for label, expected_kind in expected.items():
+            ref = _related_ref(doc.content, label)
+            if ref is None:
+                missing_related.append(label)
+                continue
+            target = docs_by_ref.get(ref)
+            if target is None:
+                broken_related.append({"kind": label, "ref": ref, "reason": "missing"})
+            elif target.kind != expected_kind:
+                broken_related.append({"kind": label, "ref": ref, "reason": f"expected {expected_kind}, found {target.kind}"})
+        if missing_related or broken_related:
+            issues.append(
+                {
+                    "ref": doc.ref,
+                    "title": doc.title,
+                    "status": doc.status,
+                    "path": doc.rel_path,
+                    "missing_related": missing_related,
+                    "broken_related": broken_related,
+                }
+            )
+    return {
+        "ok": not issues,
+        "product_count": len(product_docs),
+        "checked_product_count": len(checked_product_docs),
+        "skipped_product_count": len(product_docs) - len(checked_product_docs),
+        "issue_count": len(issues),
+        "issues": issues[:limit],
+        "truncated": len(issues) > limit,
+        "limit": limit,
+    }
+
+
+def render_product_consistency(repo_root: Path, *, output_format: str = "text", limit: int = 50) -> str:
+    payload = product_consistency_payload(repo_root, limit=limit)
+    if output_format == "json":
+        return json.dumps(payload, indent=2, sort_keys=True)
+
+    lines = [
+        "Product consistency:",
+        f"- product briefs: {payload['product_count']}",
+        f"- issue signals: {payload['issue_count']}",
+    ]
+    for issue in payload["issues"]:
+        details: list[str] = []
+        if issue["missing_related"]:
+            details.append("missing " + ", ".join(issue["missing_related"]))
+        if issue["broken_related"]:
+            details.append("broken " + ", ".join(item["ref"] for item in issue["broken_related"]))
+        lines.append(f"- {issue['ref']} [{issue['status']}]: {'; '.join(details)}")
+    return "\n".join(lines)

package/logics_manager/mcp.py

@@ -21,6 +21,7 @@ from urllib.request import Request, urlopen
 from .audit import audit_payload
 from .config import ConfigError, find_repo_root
 from .flow import flow_list_payload
+from .insights import followups_payload, health_payload, product_consistency_payload, status_payload
 from .lint import expected_workflow_mermaid_signature, lint_payload
 from .sync import append_workflow_note_payload, build_context_pack_payload, list_logics_docs_payload, read_logics_doc_payload, search_logics_docs_payload, update_workflow_indicators_payload
 
@@ -188,6 +189,37 @@ TOOL_DEFINITIONS: list[dict[str, Any]] = [
         ),
         "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
     },
+    {
+        "name": "get_logics_status",
+        "description": "Summarize open Logics workflow docs and next actions.",
+        "inputSchema": _tool_schema({"limit": {"type": "integer"}}),
+        "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
+    },
+    {
+        "name": "get_logics_health",
+        "description": "Show Logics workflow health counts and issue signals.",
+        "inputSchema": _tool_schema({"limit": {"type": "integer"}}),
+        "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
+    },
+    {
+        "name": "list_logics_followups",
+        "description": "List actionable Logics follow-up areas with request creation commands.",
+        "inputSchema": _tool_schema(
+            {
+                "source_kind": {"type": "string", "enum": ["all", "request", "backlog", "task", "product", "architecture"]},
+                "include_closed": {"type": "boolean"},
+                "closed_only": {"type": "boolean"},
+                "limit": {"type": "integer"},
+            }
+        ),
+        "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
+    },
+    {
+        "name": "check_product_consistency",
+        "description": "Check product brief lineage links for active and validated product docs.",
+        "inputSchema": _tool_schema({"limit": {"type": "integer"}}),
+        "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
+    },
     {
         "name": "finish_task",
         "description": "Finish a Logics task through the canonical flow finish task command.",
@@ -811,6 +843,24 @@ def call_tool(name: str, arguments: dict[str, Any] | None = None, *, repo_root:
         except SystemExit as exc:
             raise _mcp_read_error(exc) from exc
         return {"ok": True, **payload}
+    if name == "get_logics_status":
+        return status_payload(root, limit=_bounded_int(args.get("limit"), default=10, maximum=100))
+    if name == "get_logics_health":
+        return health_payload(root, limit=_bounded_int(args.get("limit"), default=10, maximum=100))
+    if name == "list_logics_followups":
+        include_closed = bool(args.get("include_closed", False))
+        closed_only = bool(args.get("closed_only", False))
+        if include_closed and closed_only:
+            raise McpToolError("invalid_argument_value", "include_closed and closed_only are mutually exclusive.", details={"arguments": ["include_closed", "closed_only"]})
+        return followups_payload(
+            root,
+            limit=_bounded_int(args.get("limit"), default=50, maximum=200),
+            source_kind=str(args.get("source_kind") or "all"),
+            include_closed=include_closed,
+            closed_only=closed_only,
+        )
+    if name == "check_product_consistency":
+        return product_consistency_payload(root, limit=_bounded_int(args.get("limit"), default=50, maximum=200))
     if name == "finish_task":
         rel_path = _relative_path(root, str(args.get("task_path") or ""), ("logics/tasks",))
         dry_run = bool(args.get("dry_run", False))

package/logics_manager/path_utils.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def ensure_relative_to(path: Path, root: Path, *, label: str = "path") -> Path:
+    try:
+        return path.resolve().relative_to(root.resolve())
+    except ValueError as exc:
+        raise SystemExit(f"Unsupported {label}: `{path}` is outside the repository.") from exc
+
+
+def resolve_repo_output_path(repo_root: Path, raw_path: str, *, label: str = "--out") -> tuple[Path, str]:
+    candidate = Path(raw_path)
+    if candidate.is_absolute() or any(part == ".." for part in candidate.parts):
+        raise SystemExit(f"Unsupported {label} path `{raw_path}`. Use a repo-relative path inside the repository.")
+    resolved = (repo_root / candidate).resolve()
+    relative = ensure_relative_to(resolved, repo_root, label=label)
+    return resolved, relative.as_posix()
+
+
+def resolve_repo_config_path(repo_root: Path, raw_path: str, *, label: str = "configured path") -> tuple[Path, str]:
+    candidate = Path(raw_path)
+    if any(part == ".." for part in candidate.parts):
+        raise SystemExit(f"Unsupported {label} path `{raw_path}`. Use a repo-relative path or absolute path inside the repository.")
+    resolved = candidate.resolve() if candidate.is_absolute() else (repo_root / candidate).resolve()
+    try:
+        relative = ensure_relative_to(resolved, repo_root, label=label)
+    except SystemExit as exc:
+        raise SystemExit(f"Unsupported {label} path `{raw_path}`. Use a repo-relative path or absolute path inside the repository.") from exc
+    return resolved, relative.as_posix()