@grifhinz/logics-manager 2.1.2 → 2.3.0

package/logics_manager/assist.py

@@ -11,9 +11,12 @@ import subprocess
 from shutil import which
 from typing import Any
 
+from .assist_handoff import build_handoff as _build_handoff
+from .assist_surface import build_changed_surface_summary as _build_changed_surface_summary
 from .config import ConfigError, find_repo_root, load_repo_config
 from .doctor import doctor_payload
 from .lint import lint_payload
+from .path_utils import resolve_repo_config_path, resolve_repo_output_path
 from .termstyle import colorize_help
 
 
@@ -88,8 +91,9 @@ def _hybrid_measurement_log(config: dict[str, object]) -> str:
     return str(_get_nested(config, "hybrid_assist", "measurement_log", default=DEFAULT_HYBRID_MEASUREMENT_LOG))
 
 
-def _repo_path(repo_root: Path, value: str | None, default: str) -> Path:
-    return (repo_root / (value or default)).resolve()
+def _repo_path(repo_root: Path, value: str | None, default: str, *, label: str) -> Path:
+    resolved, _relative = resolve_repo_config_path(repo_root, value or default, label=label)
+    return resolved
 
 
 def _parse_package_version(repo_root: Path) -> str:
@@ -723,7 +727,7 @@ def _render_diff_risk_text(payload: dict[str, object]) -> str:
 def _summarize_commit_scope(changed_paths: list[str]) -> tuple[str, str]:
     if not changed_paths:
         return "root", "No changes detected; nothing to commit."
-    if any(path.startswith("src/") for path in changed_paths):
+    if any(path.startswith("clients/vscode/src/") or path.startswith("clients/shared-web/media/") for path in changed_paths):
         return "plugin", "Plugin surface changes detected."
     if any(path.startswith("logics_manager/") for path in changed_paths):
         return "python-runtime", "Native Logics manager changes detected."
@@ -765,55 +769,20 @@ def _build_commit_plan(changed_paths: list[str]) -> dict[str, object]:
     }
 
 
-def _build_changed_surface_summary(changed_paths: list[str]) -> dict[str, object]:
-    category_counter: Counter[str] = Counter()
-    for path in changed_paths:
-        normalized = path.replace("\\", "/")
-        if normalized.startswith("src/"):
-            category_counter["plugin"] += 1
-        elif normalized.startswith("logics_manager/"):
-            category_counter["python-runtime"] += 1
-        elif normalized.startswith("logics/"):
-            category_counter["workflow-docs"] += 1
-        elif normalized.startswith("tests/") or "/tests/" in normalized or normalized.startswith("python_tests/"):
-            category_counter["tests"] += 1
-        elif normalized.endswith(".md"):
-            category_counter["docs"] += 1
-        else:
-            category_counter["other"] += 1
-    primary = category_counter.most_common(1)[0][0] if category_counter else "clean"
-    summary = {
-        "clean": "No changed surface was detected.",
-        "plugin": "The plugin surface is the dominant change area.",
-        "python-runtime": "The native Python runtime is the dominant change area.",
-        "workflow-docs": "Workflow documentation is the dominant change area.",
-        "tests": "Tests are the dominant change area.",
-        "docs": "Markdown documentation is the dominant change area.",
-        "other": "Mixed repository changes are present.",
-    }.get(primary, "Mixed repository changes are present.")
-    return {
-        "summary": summary,
-        "primary_category": primary,
-        "counts": dict(sorted(category_counter.items())),
-        "changed_paths": changed_paths,
-        "review_recommended": primary not in {"clean", "docs"} and bool(changed_paths),
-    }
-
-
 def _build_validation_checklist(changed_paths: list[str]) -> dict[str, object]:
     surface = _build_changed_surface_summary(changed_paths)
     checks: list[str] = [
-        "Run `python3 -m pytest python_tests/test_logics_manager_cli.py -q`.",
+        "Run `python3 -m pytest tests/python/test_logics_manager_cli.py -q`.",
         "Run `python3 -m compileall logics_manager`.",
         "Run `npm run lint:logics`.",
     ]
-    if any(path.startswith("src/") for path in changed_paths):
+    if any(path.startswith("clients/vscode/src/") or path.startswith("clients/shared-web/media/") for path in changed_paths):
         checks.append("Run the plugin test suite that exercises the VS Code entrypoints.")
     if any(path.startswith("logics_manager/") for path in changed_paths):
         checks.append("Smoke-test `python3 -m logics_manager --help` and the affected native subcommands.")
     if any(path.startswith("logics/") for path in changed_paths):
         checks.append("Run `python3 -m logics_manager lint --require-status` and inspect the workflow docs manually.")
-    if any(path.startswith("tests/") or path.startswith("python_tests/") for path in changed_paths):
+    if any(path.startswith("tests/") or path.startswith("tests/python/") for path in changed_paths):
         checks.append("Run the focused affected tests before broad regression sweeps.")
     if not changed_paths:
         checks.append("No validation needed beyond a clean smoke check; there are no tracked changes.")
@@ -829,15 +798,15 @@ def _build_test_impact_summary(changed_paths: list[str]) -> dict[str, object]:
     categories = _build_changed_surface_summary(changed_paths)["counts"]
     recommended: list[str] = []
     if "python-runtime" in categories:
-        recommended.append("python3 -m pytest python_tests/test_logics_manager_cli.py -q")
+        recommended.append("python3 -m pytest tests/python/test_logics_manager_cli.py -q")
     if "plugin" in categories:
         recommended.append("npm run lint")
     if "workflow-docs" in categories:
         recommended.append("npm run lint:logics")
     if "tests" in categories:
-        recommended.append("python3 -m pytest python_tests/test_logics_manager_cli.py -q")
+        recommended.append("python3 -m pytest tests/python/test_logics_manager_cli.py -q")
     if not recommended:
-        recommended.append("python3 -m pytest python_tests/test_logics_manager_cli.py -q")
+        recommended.append("python3 -m pytest tests/python/test_logics_manager_cli.py -q")
     return {
         "summary": "Recommended test order derived from the current change surface.",
         "categories": categories,
@@ -1346,6 +1315,12 @@ def build_parser() -> argparse.ArgumentParser:
     closure_summary.add_argument("--dry-run", action="store_true")
     closure_summary.set_defaults(func=cmd_closure_summary)
 
+    handoff = sub.add_parser("handoff", help="Summarize commits, changed surfaces, Logics docs, validations, and next actions.")
+    handoff.add_argument("--since", required=True)
+    handoff.add_argument("--format", choices=("text", "json"), default="text")
+    handoff.add_argument("--dry-run", action="store_true")
+    handoff.set_defaults(func=cmd_handoff)
+
     return parser
 
 
@@ -1417,11 +1392,15 @@ def _build_help() -> str:
             "  closure-summary [ref]",
             "    Summarize a delivered request, backlog item, or task.",
             "    Flags: --format {text,json}, --dry-run",
+            "  handoff",
+            "    Summarize commits, changed surfaces, Logics docs, validations, and next actions.",
+            "    Flags: --since, --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\"",
+            "  logics-manager assist handoff --since HEAD~1",
         ]
     )
 
@@ -1527,6 +1506,21 @@ def _build_command_help(command: str) -> str:
                 "  --dry-run",
             ]
         )
+    if command == "handoff":
+        return "\n".join(
+            [
+                "Logics Assist Handoff",
+                "Summarize commits, changed surfaces, Logics docs, validations, and next actions.",
+                "",
+                "Usage:",
+                "  logics-manager assist handoff --since <rev> [args...]",
+                "",
+                "Flags:",
+                "  --since",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
     if command == "roi-report":
         return "\n".join(
             [
@@ -2236,8 +2230,8 @@ def cmd_test_impact_summary(args: argparse.Namespace) -> dict[str, object]:
 def cmd_roi_report(args: argparse.Namespace) -> dict[str, object]:
     repo_root = find_repo_root(Path.cwd())
     config, config_path = load_repo_config(repo_root)
-    audit_log = _repo_path(repo_root, args.audit_log, _hybrid_audit_log(config))
-    measurement_log = _repo_path(repo_root, args.measurement_log, _hybrid_measurement_log(config))
+    audit_log = _repo_path(repo_root, args.audit_log, _hybrid_audit_log(config), label="configured audit_log")
+    measurement_log = _repo_path(repo_root, args.measurement_log, _hybrid_measurement_log(config), label="configured measurement_log")
     payload = _build_hybrid_roi_report(
         repo_root,
         audit_log=audit_log,
@@ -2251,13 +2245,16 @@ def cmd_roi_report(args: argparse.Namespace) -> dict[str, object]:
     payload["config_path"] = str(config_path.relative_to(repo_root)) if config_path is not None else None
 
     if args.out:
-        out_path = (repo_root / args.out).resolve()
+        out_path, output_path = resolve_repo_output_path(repo_root, args.out)
+        payload["output_path"] = output_path
         serialized = json.dumps(payload, indent=2, sort_keys=True) + "\n"
         if not args.dry_run:
             out_path.parent.mkdir(parents=True, exist_ok=True)
             out_path.write_text(serialized, encoding="utf-8")
-        print(f"Wrote {out_path.relative_to(repo_root)}")
-        payload["output_path"] = out_path.relative_to(repo_root).as_posix()
+        if args.format == "json":
+            print(json.dumps(payload, indent=2, sort_keys=True))
+        else:
+            print(f"Wrote {output_path}")
     elif args.format == "json":
         print(json.dumps(payload, indent=2, sort_keys=True))
     else:
@@ -2307,13 +2304,16 @@ def cmd_runtime_status(args: argparse.Namespace) -> dict[str, object]:
     }
 
     if args.out:
-        out_path = (repo_root / args.out).resolve()
+        out_path, output_path = resolve_repo_output_path(repo_root, args.out)
+        payload["output_path"] = output_path
         serialized = json.dumps(payload, indent=2, sort_keys=True) + "\n"
         if not args.dry_run:
             out_path.parent.mkdir(parents=True, exist_ok=True)
             out_path.write_text(serialized, encoding="utf-8")
-        print(f"Wrote {out_path.relative_to(repo_root)}")
-        payload["output_path"] = out_path.relative_to(repo_root).as_posix()
+        if args.format == "json":
+            print(json.dumps(payload, indent=2, sort_keys=True))
+        else:
+            print(f"Wrote {output_path}")
     elif args.format == "json":
         print(json.dumps(payload, indent=2, sort_keys=True))
     else:
@@ -2363,14 +2363,14 @@ def cmd_request_draft(args: argparse.Namespace) -> dict[str, object]:
         **_build_request_draft(repo_root, intent=args.intent),
     }
     if args.execution_mode == "execute":
-        out_path = repo_root / payload["path"]
+        out_path, output_path = resolve_repo_output_path(repo_root, str(payload["path"]), label="output")
         if not args.dry_run:
             out_path.parent.mkdir(parents=True, exist_ok=True)
             out_path.write_text(payload["content"], encoding="utf-8")
             payload["written"] = True
         else:
             payload["written"] = False
-        payload["output_path"] = out_path.relative_to(repo_root).as_posix()
+        payload["output_path"] = output_path
     else:
         payload["written"] = False
     if args.format == "json":
@@ -2409,14 +2409,14 @@ def cmd_spec_first_pass(args: argparse.Namespace) -> dict[str, object]:
         **_build_spec_first_pass(repo_root, args.ref),
     }
     if args.execution_mode == "execute":
-        out_path = repo_root / payload["path"]
+        out_path, output_path = resolve_repo_output_path(repo_root, str(payload["path"]), label="output")
         if not args.dry_run:
             out_path.parent.mkdir(parents=True, exist_ok=True)
             out_path.write_text(payload["content"], encoding="utf-8")
             payload["written"] = True
         else:
             payload["written"] = False
-        payload["output_path"] = out_path.relative_to(repo_root).as_posix()
+        payload["output_path"] = output_path
     else:
         payload["written"] = False
     if args.format == "json":
@@ -2455,16 +2455,16 @@ def cmd_backlog_groom(args: argparse.Namespace) -> dict[str, object]:
         **_build_backlog_groom(repo_root, args.ref),
     }
     if args.execution_mode == "execute":
-        out_path = repo_root / payload["path"]
+        out_path, output_path = resolve_repo_output_path(repo_root, str(payload["path"]), label="output")
         if not args.dry_run:
             out_path.parent.mkdir(parents=True, exist_ok=True)
             out_path.write_text(payload["content"], encoding="utf-8")
             payload["written"] = True
-            request_path = repo_root / payload["request_path"]
+            request_path, _request_output_path = resolve_repo_output_path(repo_root, str(payload["request_path"]), label="request_path")
             _append_section_bullets(request_path, "Backlog", [f"`{payload['ref']}`"], dry_run=False)
         else:
             payload["written"] = False
-        payload["output_path"] = out_path.relative_to(repo_root).as_posix()
+        payload["output_path"] = output_path
     else:
         payload["written"] = False
     if args.format == "json":
@@ -2513,6 +2513,34 @@ def cmd_closure_summary(args: argparse.Namespace) -> dict[str, object]:
     return payload
 
 
+def cmd_handoff(args: argparse.Namespace) -> dict[str, object]:
+    repo_root = find_repo_root(Path.cwd())
+    config, config_path = load_repo_config(repo_root)
+    payload = {
+        "command": "assist",
+        "kind": "handoff",
+        "repo_root": repo_root.as_posix(),
+        "config_path": str(config_path.relative_to(repo_root)) if config_path is not None else None,
+        **_build_handoff(repo_root, args.since),
+    }
+    if args.format == "json":
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(f"Handoff since {payload['since']}:")
+        print(f"- commits: {payload['commit_count']}")
+        print(f"- changed paths: {len(payload['changed_paths'])}")
+        print(f"- primary surface: {payload['surface']['primary_category']}")
+        for commit in payload["commits"][:8]:
+            print(f"- commit: {commit['commit']} {commit['subject']}")
+        for doc in payload["logics_docs"][:8]:
+            print(f"- logics: {doc['ref']} [{doc['status']}] {doc['path']}")
+        for validation in payload["validations"][:8]:
+            print(f"- validation: {validation}")
+        for action in payload["next_actions"]:
+            print(f"- next: {action}")
+    return payload
+
+
 def cmd_context(args: argparse.Namespace) -> dict[str, object]:
     repo_root = find_repo_root(Path.cwd())
     config, config_path = load_repo_config(repo_root)
@@ -2554,13 +2582,16 @@ def cmd_context(args: argparse.Namespace) -> dict[str, object]:
     }
 
     if args.out:
-        out_path = (repo_root / args.out).resolve()
+        out_path, output_path = resolve_repo_output_path(repo_root, args.out)
+        payload["output_path"] = output_path
         serialized = json.dumps(payload, indent=2, sort_keys=True) + "\n"
         if not args.dry_run:
             out_path.parent.mkdir(parents=True, exist_ok=True)
             out_path.write_text(serialized, encoding="utf-8")
-        print(f"Wrote {out_path.relative_to(repo_root)}")
-        payload["output_path"] = out_path.relative_to(repo_root).as_posix()
+        if args.format == "json":
+            print(json.dumps(payload, indent=2, sort_keys=True))
+        else:
+            print(f"Wrote {output_path}")
     elif args.format == "json":
         print(json.dumps(payload, indent=2, sort_keys=True))
     else:
@@ -2576,7 +2607,7 @@ 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:
+    if argv[0] in {"runtime-status", "context", "request-draft", "spec-first-pass", "backlog-groom", "closure-summary", "handoff", "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()

package/logics_manager/assist_handoff.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from pathlib import Path
+import subprocess
+
+from .assist_surface import build_changed_surface_summary
+
+
+def _git_lines(repo_root: Path, args: list[str]) -> list[str]:
+    try:
+        completed = subprocess.run(
+            ["git", *args],
+            cwd=repo_root,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return []
+    if completed.returncode != 0:
+        return []
+    return [line.strip() for line in completed.stdout.splitlines() if line.strip()]
+
+
+def _git_range_changed_paths(repo_root: Path, since: str) -> list[str]:
+    return sorted(set(_git_lines(repo_root, ["diff", "--name-only", f"{since}..HEAD"])))
+
+
+def _git_range_commits(repo_root: Path, since: str) -> list[dict[str, str]]:
+    commits: list[dict[str, str]] = []
+    for line in _git_lines(repo_root, ["log", "--oneline", f"{since}..HEAD"]):
+        commit, _, subject = line.partition(" ")
+        commits.append({"commit": commit, "subject": subject})
+    return commits
+
+
+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 _doc_status(path: Path) -> str:
+    for line in path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if stripped.startswith("> Status:"):
+            return stripped.split(":", 1)[1].strip()
+    return "Unknown"
+
+
+def _doc_title_from_path(path: Path) -> str:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return path.stem
+    for line in lines:
+        if line.startswith("## "):
+            payload = line.removeprefix("## ").strip()
+            if " - " in payload:
+                return payload.split(" - ", 1)[1].strip()
+            return payload
+    return path.stem
+
+
+def _validation_lines_from_task(path: Path) -> list[str]:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return []
+    values: list[str] = []
+    for line in _section_lines(lines, "Validation"):
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        value = stripped[2:].strip()
+        if value and not value.lower().startswith("run `") and not value.lower().startswith("run the "):
+            values.append(value)
+    return values
+
+
+def build_handoff(repo_root: Path, since: str) -> dict[str, object]:
+    changed_paths = _git_range_changed_paths(repo_root, since)
+    commits = _git_range_commits(repo_root, since)
+    surface = build_changed_surface_summary(changed_paths)
+    logics_docs: list[dict[str, object]] = []
+    validations: list[str] = []
+    for rel_path in changed_paths:
+        if not rel_path.startswith("logics/") or not rel_path.endswith(".md"):
+            continue
+        path = repo_root / rel_path
+        kind = path.parent.name
+        entry = {
+            "path": rel_path,
+            "ref": path.stem,
+            "kind": kind,
+            "title": _doc_title_from_path(path),
+            "status": _doc_status(path) if path.is_file() else "Unknown",
+        }
+        logics_docs.append(entry)
+        if kind == "tasks":
+            validations.extend(_validation_lines_from_task(path))
+    next_actions = [
+        "Run lint/audit if not already included in validation evidence.",
+        "Review changed files before committing or handing off.",
+    ]
+    if any(path.startswith("logics_manager/") for path in changed_paths):
+        next_actions.append("Run `PYTHONPATH=\"$PWD\" pytest tests/python -q` for Python CLI changes.")
+    if any(path.startswith("clients/vscode/src/") or path.startswith("clients/shared-web/media/") for path in changed_paths):
+        next_actions.append("Run the TypeScript/vitest checks for extension changes.")
+    return {
+        "since": since,
+        "commit_count": len(commits),
+        "commits": commits,
+        "changed_paths": changed_paths,
+        "surface": surface,
+        "logics_docs": logics_docs,
+        "validations": sorted(set(validations)),
+        "next_actions": next_actions,
+    }

package/logics_manager/assist_surface.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from collections import Counter
+
+
+def build_changed_surface_summary(changed_paths: list[str]) -> dict[str, object]:
+    category_counter: Counter[str] = Counter()
+    for path in changed_paths:
+        normalized = path.replace("\\", "/")
+        if normalized.startswith("clients/vscode/src/") or normalized.startswith("clients/shared-web/media/"):
+            category_counter["plugin"] += 1
+        elif normalized.startswith("logics_manager/"):
+            category_counter["python-runtime"] += 1
+        elif normalized.startswith("logics/"):
+            category_counter["workflow-docs"] += 1
+        elif normalized.startswith("tests/") or "/tests/" in normalized or normalized.startswith("tests/python/"):
+            category_counter["tests"] += 1
+        elif normalized.endswith(".md"):
+            category_counter["docs"] += 1
+        else:
+            category_counter["other"] += 1
+    primary = category_counter.most_common(1)[0][0] if category_counter else "clean"
+    summary = {
+        "clean": "No changed surface was detected.",
+        "plugin": "The plugin surface is the dominant change area.",
+        "python-runtime": "The native Python runtime is the dominant change area.",
+        "workflow-docs": "Workflow documentation is the dominant change area.",
+        "tests": "Tests are the dominant change area.",
+        "docs": "Markdown documentation is the dominant change area.",
+        "other": "Mixed repository changes are present.",
+    }.get(primary, "Mixed repository changes are present.")
+    return {
+        "summary": summary,
+        "primary_category": primary,
+        "counts": dict(sorted(category_counter.items())),
+        "changed_paths": changed_paths,
+        "review_recommended": primary not in {"clean", "docs"} and bool(changed_paths),
+    }