@grifhinz/logics-manager 2.0.2 → 2.0.5

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/AlexAgo83/logics-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/AlexAgo83/logics-manager/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/AlexAgo83/logics-manager)](LICENSE)
-![Version](https://img.shields.io/badge/version-v2.0.2-4C8BF5)
+![Version](https://img.shields.io/badge/version-v2.0.5-4C8BF5)
 ![VS Code](https://img.shields.io/badge/VS%20Code-1.86.0-007ACC?logo=visualstudiocode&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.3.3-3178C6?logo=typescript&logoColor=white)
 ![Vitest](https://img.shields.io/badge/Vitest-2.1.8-6E9F18?logo=vitest&logoColor=white)
@@ -35,6 +35,9 @@ Install the npm package with:
 npm install -g @grifhinz/logics-manager
 ```
 
+To update that CLI later, run `logics-manager self-update`.
+The command uses `pip` when the Python package is installed and falls back to `npm` for the global npm package.
+
 For the editor client, build and install the VSIX:
 
 ```bash
@@ -163,7 +166,7 @@ Windows notes:
 
 ### Install from Marketplace
 
-https://marketplace.visualstudio.com/items?itemName=cdx-logics.logics-manager
+https://marketplace.visualstudio.com/items?itemName=cdx-logics.cdx-logics-vscode
 
 ### Install from VSIX (recommended for users)
 
@@ -267,7 +270,7 @@ Contract:
 - `Environment` can also surface direct remediation actions when the plugin detects a stale runtime, an incomplete bootstrap, a missing global publication, or missing environment placeholders.
 - `Environment` now uses a clearer hierarchy with summary, recommended actions, current status, and technical details, plus hybrid assist runtime state, backend availability, degraded reasons, Claude-bridge presence, and the shared Windows-safe runtime entrypoint.
 - `Check Environment` can be promoted into `Recommended` when the current repo state actually warrants operator attention.
-- repo-local refresh now watches `logics/**/*`, `logics.yaml`, and supported `.claude/` bridge files; external global runtime state still requires an explicit refresh because it lives outside the workspace.
+- repo-local refresh now watches `logics/**/*`, `logics.yaml`, and `.git/HEAD`; external global runtime state still requires an explicit refresh because it lives outside the workspace.
 - `Launch Codex` starts Codex using the globally published Logics runtime when the shared runtime is healthy.
 - `AI Runtime Status` probes the shared `logics.py flow assist runtime-status` surface and reports ready providers, flagged providers, cooldown or credential issues, and bounded backend provenance.
 - `AI Provider Insights` opens a dedicated plugin panel backed by `logics.py flow assist roi-report`, with provider mix, execution-path breakdowns, derived rates, estimated ROI proxies, and recent audit drill-down over the shared runtime output.

package/VERSION

@@ -1 +1 @@
-2.0.2
+2.0.5

package/logics_manager/assist.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 from collections import Counter
 from datetime import datetime, timedelta, timezone
 import re
@@ -13,6 +14,7 @@ from typing import Any
 from .config import ConfigError, find_repo_root, load_repo_config
 from .doctor import doctor_payload
 from .lint import lint_payload
+from .termstyle import colorize_help
 
 
 DEFAULT_HYBRID_AUDIT_LOG = "logics/.cache/hybrid_assist_audit.jsonl"
@@ -20,6 +22,7 @@ DEFAULT_HYBRID_MEASUREMENT_LOG = "logics/.cache/hybrid_assist_measurements.jsonl
 DEFAULT_HYBRID_ROI_RECENT_LIMIT = 8
 DEFAULT_HYBRID_ROI_WINDOW_DAYS = 14
 DEFAULT_ESTIMATED_REMOTE_TOKENS_PER_LOCAL_RUN = 1200
+HELP_FLAGS = ("-h", "--help")
 
 
 CLAUDE_BRIDGE_VARIANTS: tuple[dict[str, object], ...] = (
@@ -1283,7 +1286,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     claude_bridges = sub.add_parser(
         "claude-bridges",
-        help="Render the canonical Claude bridge files and prompts derived from the integrated runtime.",
+        help="Render the canonical Claude runtime publication manifest and prompts derived from the integrated runtime.",
     )
     claude_bridges.add_argument("--format", choices=("text", "json"), default="text")
     claude_bridges.add_argument("--dry-run", action="store_true")
@@ -1346,10 +1349,375 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def _claude_bridge_status(repo_root: Path) -> dict[str, object]:
+def _build_help() -> str:
+    return "\n".join(
+        [
+            "Logics Assist CLI",
+            "Inspect runtime signals and build context bundles.",
+            "",
+            "Usage:",
+            "  logics-manager assist <command> [args...]",
+            "",
+            "Runtime and diagnostics:",
+            "  runtime-status",
+            "    Report local assist runtime readiness.",
+            "    Flags: --backend, --model-profile, --model, --ollama-host, --timeout, --format {text,json}, --out, --dry-run",
+            "  diff-risk",
+            "    Classify the current git diff using deterministic heuristics.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  commit-plan",
+            "    Draft a minimal commit plan from the current git diff.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  changed-surface-summary",
+            "    Summarize the current changed repository surface.",
+            "    Flags: --format {text,json}, --dry-run",
+            "",
+            "Review and governance:",
+            "  doc-consistency",
+            "    Review workflow docs for consistency issues without mutating them.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  review-checklist",
+            "    Generate a bounded review checklist for the current change surface.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  validation-checklist",
+            "    Generate a deterministic validation checklist from the current change surface.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  validation-summary",
+            "    Summarize lint, doctor, and validation impact signals.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  test-impact-summary",
+            "    Summarize the likely test impact of the current change surface.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  roi-report",
+            "    Summarize hybrid assist ROI from local audit and measurement logs.",
+            "    Flags: --audit-log, --measurement-log, --recent-limit, --window-days, --format {text,json}, --out, --dry-run",
+            "",
+            "Context and prompts:",
+            "  claude-bridges",
+            "    Render the canonical Claude runtime publication manifest and prompts.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  context <flow_name> [ref]",
+            "    Build a shared assist context bundle for a flow.",
+            "    Flags: --context-mode {summary-only,diff-first,full}, --profile {tiny,normal,deep}, --include-graph, --include-registry, --include-doctor, --format {text,json}, --out, --dry-run",
+            "  claude-instructions",
+            "    Render the canonical assistant instructions derived from the integrated runtime.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  next-step [ref]",
+            "    Suggest the next bounded Logics step for a target doc.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  request-draft",
+            "    Draft a bounded request doc from an intent.",
+            "    Flags: --intent, --format {text,json}, --execution-mode {suggestion-only,execute}, --dry-run",
+            "  spec-first-pass <ref>",
+            "    Draft a first-pass spec outline from a backlog item.",
+            "    Flags: --format {text,json}, --execution-mode {suggestion-only,execute}, --dry-run",
+            "  backlog-groom <ref>",
+            "    Draft a bounded backlog proposal from a request doc.",
+            "    Flags: --format {text,json}, --execution-mode {suggestion-only,execute}, --dry-run",
+            "  closure-summary [ref]",
+            "    Summarize a delivered request, backlog item, or task.",
+            "    Flags: --format {text,json}, --dry-run",
+            "",
+            "Examples:",
+            "  logics-manager assist runtime-status --format json",
+            "  logics-manager assist context request req_001_my_request --profile deep",
+            "  logics-manager assist request-draft --intent \"Improve onboarding\"",
+        ]
+    )
+
+
+def _build_command_help(command: str) -> str:
+    if command == "runtime-status":
+        return "\n".join(
+            [
+                "Logics Assist Runtime Status",
+                "Report local assist runtime readiness.",
+                "",
+                "Usage:",
+                "  logics-manager assist runtime-status [args...]",
+                "",
+                "Flags:",
+                "  --backend",
+                "  --model-profile",
+                "  --model",
+                "  --ollama-host",
+                "  --timeout",
+                "  --format {text,json}",
+                "  --out",
+                "  --dry-run",
+            ]
+        )
+    if command == "context":
+        return "\n".join(
+            [
+                "Logics Assist Context",
+                "Build a shared assist context bundle for a flow.",
+                "",
+                "Usage:",
+                "  logics-manager assist context <flow_name> [ref] [args...]",
+                "",
+                "Flags:",
+                "  --context-mode {summary-only,diff-first,full}",
+                "  --profile {tiny,normal,deep}",
+                "  --include-graph",
+                "  --include-registry",
+                "  --include-doctor",
+                "  --format {text,json}",
+                "  --out",
+                "  --dry-run",
+            ]
+        )
+    if command == "request-draft":
+        return "\n".join(
+            [
+                "Logics Assist Request Draft",
+                "Draft a bounded request doc from an intent.",
+                "",
+                "Usage:",
+                "  logics-manager assist request-draft [args...]",
+                "",
+                "Flags:",
+                "  --intent",
+                "  --format {text,json}",
+                "  --execution-mode {suggestion-only,execute}",
+                "  --dry-run",
+            ]
+        )
+    if command == "spec-first-pass":
+        return "\n".join(
+            [
+                "Logics Assist Spec First Pass",
+                "Draft a first-pass spec outline from a backlog item.",
+                "",
+                "Usage:",
+                "  logics-manager assist spec-first-pass <ref> [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --execution-mode {suggestion-only,execute}",
+                "  --dry-run",
+            ]
+        )
+    if command == "backlog-groom":
+        return "\n".join(
+            [
+                "Logics Assist Backlog Groom",
+                "Draft a bounded backlog proposal from a request doc.",
+                "",
+                "Usage:",
+                "  logics-manager assist backlog-groom <ref> [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --execution-mode {suggestion-only,execute}",
+                "  --dry-run",
+            ]
+        )
+    if command == "closure-summary":
+        return "\n".join(
+            [
+                "Logics Assist Closure Summary",
+                "Summarize a delivered request, backlog item, or task.",
+                "",
+                "Usage:",
+                "  logics-manager assist closure-summary [ref] [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "roi-report":
+        return "\n".join(
+            [
+                "Logics Assist ROI Report",
+                "Summarize hybrid assist ROI from local audit and measurement logs.",
+                "",
+                "Usage:",
+                "  logics-manager assist roi-report [args...]",
+                "",
+                "Flags:",
+                "  --audit-log",
+                "  --measurement-log",
+                "  --recent-limit",
+                "  --window-days",
+                "  --format {text,json}",
+                "  --out",
+                "  --dry-run",
+            ]
+        )
+    if command == "diff-risk":
+        return "\n".join(
+            [
+                "Logics Assist Diff Risk",
+                "Classify the current git diff using deterministic heuristics.",
+                "",
+                "Usage:",
+                "  logics-manager assist diff-risk [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "commit-plan":
+        return "\n".join(
+            [
+                "Logics Assist Commit Plan",
+                "Draft a minimal commit plan from the current git diff.",
+                "",
+                "Usage:",
+                "  logics-manager assist commit-plan [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "changed-surface-summary":
+        return "\n".join(
+            [
+                "Logics Assist Changed Surface Summary",
+                "Summarize the current changed repository surface.",
+                "",
+                "Usage:",
+                "  logics-manager assist changed-surface-summary [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "doc-consistency":
+        return "\n".join(
+            [
+                "Logics Assist Doc Consistency",
+                "Review workflow docs for consistency issues without mutating them.",
+                "",
+                "Usage:",
+                "  logics-manager assist doc-consistency [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "review-checklist":
+        return "\n".join(
+            [
+                "Logics Assist Review Checklist",
+                "Generate a bounded review checklist for the current change surface.",
+                "",
+                "Usage:",
+                "  logics-manager assist review-checklist [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "validation-checklist":
+        return "\n".join(
+            [
+                "Logics Assist Validation Checklist",
+                "Generate a deterministic validation checklist from the current change surface.",
+                "",
+                "Usage:",
+                "  logics-manager assist validation-checklist [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "validation-summary":
+        return "\n".join(
+            [
+                "Logics Assist Validation Summary",
+                "Summarize lint, doctor, and validation impact signals.",
+                "",
+                "Usage:",
+                "  logics-manager assist validation-summary [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "test-impact-summary":
+        return "\n".join(
+            [
+                "Logics Assist Test Impact Summary",
+                "Summarize the likely test impact of the current change surface.",
+                "",
+                "Usage:",
+                "  logics-manager assist test-impact-summary [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "claude-bridges":
+        return "\n".join(
+            [
+                "Logics Assist Claude Bridges",
+                "Render the canonical Claude runtime publication manifest and prompts.",
+                "",
+                "Usage:",
+                "  logics-manager assist claude-bridges [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "claude-instructions":
+        return "\n".join(
+            [
+                "Logics Assist Claude Instructions",
+                "Render the canonical assistant instructions derived from the integrated runtime.",
+                "",
+                "Usage:",
+                "  logics-manager assist claude-instructions [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "next-step":
+        return "\n".join(
+            [
+                "Logics Assist Next Step",
+                "Suggest the next bounded Logics step for a target doc.",
+                "",
+                "Usage:",
+                "  logics-manager assist next-step [ref] [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    return _build_help()
+
+
+def _print_help(text: str) -> None:
+    print(colorize_help(text))
+
+
+def _get_global_claude_home() -> Path:
+    return Path(os.environ.get("LOGICS_CLAUDE_GLOBAL_HOME") or (Path.home() / ".claude")).resolve()
+
+
+def _claude_bridge_status(_repo_root: Path) -> dict[str, object]:
+    global_home = _get_global_claude_home()
     detected_variants: list[str] = []
     for variant in CLAUDE_BRIDGE_VARIANTS:
-        if (repo_root / variant["command_path"]).is_file() and (repo_root / variant["agent_path"]).is_file():
+        command_path = global_home / str(variant["command_path"]).replace(".claude/", "")
+        agent_path = global_home / str(variant["agent_path"]).replace(".claude/", "")
+        if command_path.is_file() and agent_path.is_file():
             detected_variants.append(variant["id"])
     return {
         "available": bool(detected_variants),
@@ -1368,7 +1736,7 @@ def _render_claude_bridge_lines(variant: dict[str, object], prompt: str) -> tupl
     command_lines = [
         f"# {title}",
         "",
-        f"Use the repository-local {title.lower()} bridge for this project.",
+        f"Use the published global {title.lower()} bridge for this project.",
         "",
         "Primary prompt:",
         prompt,
@@ -1377,7 +1745,7 @@ def _render_claude_bridge_lines(variant: dict[str, object], prompt: str) -> tupl
     agent_lines = [
         f"# {title} Agent",
         "",
-        f"Use the repository-local {title.lower()} agent for this project.",
+        f"Use the published global {title.lower()} agent for this project.",
         "",
         "Default prompt:",
         prompt,
@@ -1433,8 +1801,8 @@ def _build_claude_instructions(repo_root: Path) -> dict[str, object]:
             "- `python3 -m logics_manager lint --require-status`",
             "- `python3 -m logics_manager audit --legacy-cutoff-version 1.1.0 --group-by-doc`",
             "",
-            "Repository-local Claude bridge files and assistant instructions are generated from the integrated runtime.",
-            "Do not edit `.claude/` bridge files by hand unless you are deliberately repairing a generated artifact.",
+            "Claude runtime artifacts are generated outside the repository from the integrated runtime.",
+            "Do not edit generated runtime artifacts by hand unless you are deliberately repairing a generated artifact.",
             "",
             "Do not edit indicator lines or workflow links by hand.",
             "",
@@ -1454,8 +1822,8 @@ def _select_backend(requested_backend: str | None, bridge_status: dict[str, obje
     if requested_backend and requested_backend != "auto":
         return requested_backend, []
     if bridge_status.get("available"):
-        return "codex", ["claude bridge files detected"]
-    return "deterministic", ["no bridge files detected"]
+        return "codex", ["global Claude runtime published"]
+    return "deterministic", ["no global Claude runtime published"]
 
 
 def cmd_claude_bridges(args: argparse.Namespace) -> dict[str, object]:
@@ -1953,9 +2321,9 @@ def cmd_runtime_status(args: argparse.Namespace) -> dict[str, object]:
         print(f"- selected backend: {selected_backend}")
         print(f"- model profile: {default_profile}")
         print(f"- model: {resolved_model}")
-        print(f"- bridge available: {'yes' if bridge_status['available'] else 'no'}")
+        print(f"- global Claude runtime available: {'yes' if bridge_status['available'] else 'no'}")
         if bridge_status["preferred_variant"]:
-            print(f"- bridge variant: {bridge_status['preferred_variant']}")
+            print(f"- runtime variant: {bridge_status['preferred_variant']}")
     return payload
 
 
@@ -2200,11 +2568,17 @@ def cmd_context(args: argparse.Namespace) -> dict[str, object]:
         print(f"- ref: {args.ref or '<flow-default>'}")
         print(f"- mode: {context_mode}")
         print(f"- profile: {profile}")
-        print(f"- bridge available: {'yes' if bridge_status['available'] else 'no'}")
+        print(f"- global Claude runtime available: {'yes' if bridge_status['available'] else 'no'}")
     return payload
 
 
 def main(argv: list[str]) -> int:
+    if not argv or argv[0] in HELP_FLAGS:
+        _print_help(_build_help())
+        return 0
+    if argv[0] in {"runtime-status", "context", "request-draft", "spec-first-pass", "backlog-groom", "closure-summary", "roi-report", "diff-risk", "commit-plan", "changed-surface-summary", "doc-consistency", "review-checklist", "validation-checklist", "validation-summary", "test-impact-summary", "claude-bridges", "claude-instructions", "next-step"} and len(argv) > 1 and argv[1] in HELP_FLAGS:
+        _print_help(_build_command_help(argv[0]))
+        return 0
     parser = build_parser()
     args = parser.parse_args(argv)
     payload = args.func(args)

package/logics_manager/bootstrap.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
 import json
+import shutil
 from pathlib import Path
 
-from .assist import _build_claude_bridge_manifest, _build_claude_instructions
+from .assist import _build_claude_instructions
 
 
 WORKFLOW_DIRS: tuple[str, ...] = ("request", "backlog", "tasks", "specs", "product", "architecture", "external", ".cache")
@@ -13,14 +14,34 @@ def _workflow_directories(repo_root: Path) -> list[Path]:
     return [repo_root / "logics" / name for name in WORKFLOW_DIRS]
 
 
+def _legacy_runtime_paths(repo_root: Path) -> list[Path]:
+    return [repo_root / ".claude", repo_root / "logics" / "skills"]
+
+
+def _remove_legacy_runtime_paths(repo_root: Path, *, check: bool) -> list[str]:
+    removed_paths: list[str] = []
+    for target in _legacy_runtime_paths(repo_root):
+        if not target.exists():
+            continue
+        removed_paths.append(target.relative_to(repo_root).as_posix() + ("/" if target.is_dir() else ""))
+        if not check:
+            if target.is_dir():
+                shutil.rmtree(target)
+            else:
+                target.unlink()
+    return removed_paths
+
+
 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] = []
+    removed_paths: list[str] = []
     missing_paths: list[str] = []
 
+    removed_paths.extend(_remove_legacy_runtime_paths(repo_root, check=check))
+
     if not logics_root.exists():
         missing_paths.append("logics/")
     elif not logics_root.is_dir():
@@ -71,24 +92,6 @@ def bootstrap_payload(repo_root: Path, *, check: bool) -> dict[str, object]:
             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",
@@ -97,8 +100,8 @@ def bootstrap_payload(repo_root: Path, *, check: bool) -> dict[str, object]:
         "ok": ok,
         "missing_paths": missing_paths,
         "created_paths": created_paths,
+        "removed_paths": removed_paths,
         "directory_actions": directory_actions,
-        "claude_bridge_count": bridge_manifest["bridge_count"],
         "claude_instruction_line_count": instructions_manifest["line_count"],
     }
 
@@ -114,6 +117,10 @@ def render_bootstrap(payload: dict[str, object], *, output_format: str) -> str:
             lines.append(f"- missing: {path}")
         return "\n".join(lines)
     lines = ["Bootstrap: OK"]
+    if payload.get("removed_paths"):
+        lines.append("- removed:")
+        for path in payload["removed_paths"]:
+            lines.append(f"  - {path}")
     if payload["created_paths"]:
         lines.append("- created:")
         for path in payload["created_paths"]: