logics-manager 2.1.2__tar.gz → 2.2.0__tar.gz

{logics_manager-2.1.2 → logics_manager-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logics-manager
-Version: 2.1.2
+Version: 2.2.0
 Summary: Canonical Logics CLI
 Requires-Python: >=3.10
 License-File: LICENSE

{logics_manager-2.1.2 → logics_manager-2.2.0}/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.1.2-4C8BF5)
+![Version](https://img.shields.io/badge/version-v2.2.0-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)
@@ -101,12 +101,55 @@ Useful commands:
 
 ```bash
 logics-manager flow list
-logics-manager flow promote request-to-backlog logics/request/req_001_example.md
-logics-manager flow promote backlog-to-task logics/backlog/item_001_example.md
-logics-manager flow finish task logics/tasks/task_001_example.md
+logics-manager flow promote request-to-backlog req_001_example
+logics-manager flow promote backlog-to-task item_001_example
+logics-manager flow finish task task_001_example
 logics-manager sync context-pack req_001_example --format json
 ```
 
+### CLI Contracts
+
+Workflow target arguments accept these forms:
+
+- a workflow ref, such as `req_001_example`, `item_001_example`, or `task_001_example`;
+- a repo-relative Markdown path under the matching Logics directory, such as `logics/request/req_001_example.md`;
+- an absolute path only when it resolves inside the current repository.
+
+Mutation commands reject `..` traversal and files outside the repository before writing. Output paths passed with `--out` must also be repo-relative and remain inside the repository after resolution. Configured log/cache paths in `logics.yaml` may be repo-relative or absolute, but absolute paths must still resolve inside the current repository.
+
+When a command supports `--format json`, stdout is a machine-readable JSON payload. Human-oriented status, diagnostics, and progress text should not be mixed into stdout for JSON mode. This makes JSON-mode commands safe to pipe into tools such as `jq` or consume from scripts.
+
+`--json` is a shorthand for `--format json` on commands that support JSON output.
+
+JSON-capable operator commands:
+
+| Command | Purpose | JSON output |
+| --- | --- | --- |
+| `logics-manager status` | Summarize open workflow docs and next actions. | `--format json` or `--json` |
+| `logics-manager health` | Show workflow health counts and issue signals. | `--format json` or `--json` |
+| `logics-manager followups` | List follow-up areas with request creation commands. | `--format json` or `--json` |
+| `logics-manager product-consistency` | Check product brief lineage links. | `--format json` or `--json` |
+| `logics-manager search <query>` | Search workflow docs directly. | `--format json` or `--json` |
+| `logics-manager index` | Regenerate `logics/INDEX.md`. | `--format json` or `--json` |
+| `logics-manager lint` | Validate doc shape and changed-doc hygiene. | `--format json` or `--json` |
+| `logics-manager audit` | Validate workflow traceability and governance. | `--format json` or `--json` |
+| `logics-manager sync ...` | Read, list, search, repair, and export workflow state. | `--format json` or `--json` on supported subcommands |
+| `logics-manager assist ...` | Build review, validation, context, and runtime summaries. | `--format json` or `--json` on supported subcommands |
+| `logics-manager flow ...` | Create, promote, split, close, finish, and list docs. | `--format json` or `--json` on supported subcommands |
+
+Operator triage flow:
+
+```bash
+logics-manager status --json
+logics-manager health --json
+logics-manager product-consistency --json
+logics-manager followups --source-kind product --json
+```
+
+Use `status` first when you need the next work signal. Use `health` for corpus-level anomalies. Use `product-consistency --strict` in release checks when active product briefs must have valid lineage. Use `followups` for open actionable follow-up areas; add `--include-closed` only when auditing historical docs.
+
+Multi-file workflow mutations such as `flow promote`, `flow split`, and `flow finish` validate their direct inputs before writing. New workflow docs are created with exclusive filesystem writes, so an ID collision fails instead of overwriting an existing file; rerun the command to allocate a fresh ID after reviewing `git status`/`git diff`. They still operate on Markdown files in the working tree rather than through a database or transaction service; if the filesystem fails mid-write, recover with git status/diff and rerun after cleanup.
+
 To update the installed CLI later:
 
 ```bash

{logics_manager-2.1.2 → logics_manager-2.2.0}/logics_manager/assist.py

@@ -14,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 .path_utils import resolve_repo_config_path, resolve_repo_output_path
 from .termstyle import colorize_help
 
 
@@ -88,8 +89,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:
@@ -641,6 +643,35 @@ def _git_changed_paths(repo_root: Path) -> list[str]:
     return [line.strip() for line in completed.stdout.splitlines() if line.strip()]
 
 
+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", "--relative=.", 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 _is_low_risk_generated_path(path: str) -> bool:
     normalized = path.strip().replace("\\", "/")
     filename = normalized.rsplit("/", 1)[-1]
@@ -1346,6 +1377,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 +1454,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 +1568,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(
             [
@@ -2023,6 +2079,77 @@ def _build_closure_summary(repo_root: Path, ref: str | None) -> dict[str, object
     }
 
 
+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 python_tests -q` for Python CLI changes.")
+    if any(path.startswith("src/") 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,
+    }
+
+
 def _build_context_pack(repo_root: Path, seed_ref: str, *, mode: str, profile: str) -> dict[str, object]:
     docs = _workflow_docs(repo_root)
     selected: list[Path] = []
@@ -2236,8 +2363,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 +2378,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 +2437,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 +2496,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 +2542,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 +2588,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 +2646,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 +2715,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 +2740,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()