@grifhinz/logics-manager 2.7.0 → 2.8.1

package/logics_manager/flow.py

@@ -15,6 +15,7 @@ from .flow_evidence import structured_validation_line as _structured_validation_
 from .index import index_payload
 from .lint import expected_workflow_mermaid_signature, lint_payload
 from .path_utils import ensure_relative_to
+from .sync import read_logics_doc_payload
 from .termstyle import colorize_help
 
 
@@ -206,6 +207,10 @@ def _build_help() -> str:
             "    List workflow docs that are still active.",
             "    Flags: --kind {all,request,backlog,task}, --format {text,json}",
             "",
+            "  show <ref>",
+            "    Show a bounded workflow document view.",
+            "    Flags: --max-chars, --section, --format {text,json}",
+            "",
             "  companion <product|architecture>",
             "    Create a companion doc from the integrated runtime.",
             "    Flags: --title, --source-ref, --request-ref, --backlog-ref, --task-ref, --format {text,json}, --dry-run",
@@ -251,6 +256,7 @@ def _build_help() -> str:
             "Examples:",
             '  logics-manager flow new request --title "My request"',
             "  logics-manager flow deliver --from-product prod_017_delivery_loop",
+            "  logics-manager flow show req_001_my_request",
             "  logics-manager flow validate-closeout task_003_fix_docs",
             "  logics-manager flow repair gates task_003_fix_docs",
             "  logics-manager flow closeout task_003_fix_docs --validation \"pytest passed\" --index --lint --audit",
@@ -338,6 +344,27 @@ def _build_list_help() -> str:
     )
 
 
+def _build_show_help() -> str:
+    return "\n".join(
+        [
+            "Logics Flow Show",
+            "Show a bounded workflow document view.",
+            "",
+            "Usage:",
+            "  logics-manager flow show <ref-or-path> [args...]",
+            "",
+            "Flags:",
+            "  --max-chars",
+            "  --section",
+            "  --format {text,json}",
+            "",
+            "Examples:",
+            "  logics-manager flow show req_001_my_request",
+            "  logics-manager flow show task_003_fix_docs --section Validation",
+        ]
+    )
+
+
 def _build_companion_help() -> str:
     return "\n".join(
         [
@@ -2214,6 +2241,13 @@ def build_parser() -> argparse.ArgumentParser:
     list_parser.add_argument("--format", choices=("text", "json"), default="text")
     list_parser.set_defaults(func=cmd_list)
 
+    show_parser = sub.add_parser("show", help="Show a bounded workflow document view.")
+    show_parser.add_argument("source")
+    show_parser.add_argument("--max-chars", type=int, default=4000)
+    show_parser.add_argument("--section", action="append", default=[])
+    show_parser.add_argument("--format", choices=("text", "json"), default="text")
+    show_parser.set_defaults(func=cmd_show)
+
     companion_parser = sub.add_parser("companion", help="Create a companion doc from the integrated runtime.")
     companion_sub = companion_parser.add_subparsers(dest="kind", required=True)
     for kind in ("product", "architecture"):
@@ -2429,6 +2463,22 @@ def cmd_list(args: argparse.Namespace) -> dict[str, object]:
     return payload
 
 
+def cmd_show(args: argparse.Namespace) -> dict[str, object]:
+    repo_root = _find_repo_root(Path.cwd())
+    max_chars = args.max_chars if args.max_chars > 0 else 4000
+    payload = read_logics_doc_payload(repo_root, args.source, max_chars=min(max_chars, 12000), sections=args.section or None)
+    if args.format == "json":
+        print_payload({"command": "show", **payload}, args.format)
+    else:
+        print(f"{payload['ref']} ({payload['kind']}): {payload['title']}")
+        print(f"- path: {payload['path']}")
+        print(f"- status: {payload['status']}")
+        print(f"- truncated: {payload['truncated']}")
+        print("")
+        print(str(payload["content"]).rstrip())
+    return payload
+
+
 def cmd_companion(args: argparse.Namespace) -> dict[str, object]:
     repo_root = _find_repo_root(Path.cwd())
     request_ref, backlog_ref, task_ref = _resolve_workflow_refs_for_companion(
@@ -2793,6 +2843,9 @@ def closeout_payload(
     finish_payload: dict[str, object] | None = None
     if not dry_run:
         _close_chain_for_kind(repo_root, task_path, DOC_KINDS["task"], dry_run=False, quiet=True)
+        for ref in mermaid_refs:
+            if ref.startswith(f"{DOC_KINDS['request'].prefix}_"):
+                _maybe_close_request_chain(repo_root, ref, dry_run=False, quiet=True)
         finish_issues = _verify_finished_task_chain(repo_root, task_path)
         if finish_issues:
             raise SystemExit("Finish verification failed:\n" + "\n".join(f"- {issue}" for issue in finish_issues))
@@ -3244,6 +3297,9 @@ def main(argv: list[str]) -> int:
     if argv[0] == "list" and _help_requested(argv, 1):
         _print_help(_build_list_help())
         return 0
+    if argv[0] == "show" and _help_requested(argv, 1):
+        _print_help(_build_show_help())
+        return 0
     if argv[0] == "companion" and _help_requested(argv, 1):
         _print_help(_build_companion_help())
         return 0
@@ -3289,9 +3345,13 @@ def main(argv: list[str]) -> int:
     if argv[0] == "finish" and len(argv) > 1 and argv[1] == "task" and _help_requested(argv, 2):
         _print_help(_build_finish_kind_help(argv[1]))
         return 0
+    valid_commands = {"new", "list", "show", "companion", "deliver", "validate-closeout", "repair", "closeout", "promote", "split", "close", "finish"}
+    if argv[0] not in valid_commands:
+        hint = " Use `logics-manager flow show <ref>` to inspect a workflow doc." if argv[0] in {"read", "view", "cat"} else " Run `logics-manager flow --help` for valid commands."
+        raise SystemExit(f"Unsupported flow subcommand: {argv[0]}.{hint}")
     parser = build_parser()
     args = parser.parse_args(argv)
-    if args.command not in {"new", "list", "companion", "deliver", "validate-closeout", "repair", "closeout", "promote", "split", "close", "finish"}:
+    if args.command not in valid_commands:
         raise SystemExit("Unsupported flow subcommand for the native CLI slice.")
     payload = args.func(args)
     if args.command == "validate-closeout" and isinstance(payload, dict) and not payload.get("ok", False):

package/logics_manager/sync.py

@@ -259,11 +259,23 @@ def _build_context_pack(
     profile: str,
     config: dict[str, object] | None = None,
 ) -> dict[str, object]:
+    seed_refs = [ref for ref in seed_ref.split(",") if ref]
     docs = _load_workflow_docs(repo_root)
-    seed = docs.get(seed_ref)
-    if seed is None:
-        raise SystemExit(f"Unknown workflow ref `{seed_ref}`.")
-    ordered = _workflow_neighborhood(seed, docs)[: _context_profile_limit(profile)]
+    seeds = [docs.get(ref) for ref in seed_refs]
+    missing = [ref for ref, doc in zip(seed_refs, seeds) if doc is None]
+    if missing:
+        raise SystemExit(f"Unknown workflow ref(s): {', '.join(f'`{ref}`' for ref in missing)}.")
+    ordered: list[WorkflowDocModel] = []
+    seen: set[str] = set()
+    per_seed_limit = _context_profile_limit(profile)
+    for seed in seeds:
+        if seed is None:
+            continue
+        for doc in _workflow_neighborhood(seed, docs)[:per_seed_limit]:
+            if doc.ref in seen:
+                continue
+            ordered.append(doc)
+            seen.add(doc.ref)
     changed_paths = _git_changed_paths(repo_root) if mode == "diff-first" else []
     cache_key = _context_pack_cache_key(
         repo_root,
@@ -281,7 +293,8 @@ def _build_context_pack(
         "ref": seed_ref,
         "mode": mode,
         "profile": profile,
-        "budgets": {"max_docs": _context_profile_limit(profile)},
+        "refs": seed_refs,
+        "budgets": {"max_docs": per_seed_limit * max(1, len(seed_refs)), "max_docs_per_ref": per_seed_limit},
         "changed_paths": changed_paths,
         "docs": pack_docs,
         "estimates": {
@@ -725,6 +738,8 @@ def build_parser() -> argparse.ArgumentParser:
     close_eligible.set_defaults(func=cmd_close_eligible_requests)
 
     refresh_mermaid = sub.add_parser("refresh-mermaid-signatures", help="Refresh stale workflow Mermaid signatures without rewriting the full diagram body.")
+    refresh_mermaid.add_argument("sources", nargs="*", help="Optional workflow refs or paths to scope the refresh.")
+    refresh_mermaid.add_argument("--changed-only", action="store_true", help="Refresh only changed workflow docs.")
     refresh_mermaid.add_argument("--format", choices=("text", "json"), default="text")
     refresh_mermaid.add_argument("--dry-run", action="store_true")
     refresh_mermaid.set_defaults(func=cmd_refresh_mermaid_signatures)
@@ -779,7 +794,7 @@ def build_parser() -> argparse.ArgumentParser:
     append_note.set_defaults(func=cmd_append_note)
 
     context_pack = sub.add_parser("context-pack", help="Build a compact context pack from workflow docs.")
-    context_pack.add_argument("ref", help="Seed workflow ref for the context pack.")
+    context_pack.add_argument("refs", nargs="+", help="Seed workflow ref(s) for the context pack.")
     context_pack.add_argument("--mode", choices=("summary-only", "diff-first", "full"), default="summary-only")
     context_pack.add_argument("--profile", choices=("tiny", "normal", "deep"), default="normal")
     context_pack.add_argument("--out", help="Write the JSON artifact to this relative path.")
@@ -812,13 +827,14 @@ def _build_help() -> str:
             "",
             "  refresh-mermaid-signatures",
             "    Refresh stale Mermaid signatures without rewriting diagram bodies.",
-            "    Flags: --format {text,json}, --dry-run",
+            "    Args: [refs-or-paths...]",
+            "    Flags: --changed-only, --format {text,json}, --dry-run",
             "",
             "  schema-status [sources...]",
             "    Report schema-version coverage for selected workflow docs.",
             "    Flags: --format {text,json}",
             "",
-            "  context-pack <ref>",
+            "  context-pack <refs...>",
             "    Build a compact JSON context pack from workflow docs.",
             "    Flags: --mode {summary-only,diff-first,full}, --profile {tiny,normal,deep}, --out, --format {text,json}, --dry-run",
             "",
@@ -848,7 +864,7 @@ def _build_help() -> str:
             "",
             "Examples:",
             "  logics-manager sync schema-status",
-            "  logics-manager sync context-pack req_001_my_request --out logics/context-pack.json",
+            "  logics-manager sync context-pack req_001_my_request task_002_fix_bug --out logics/context-pack.json",
             "  logics-manager sync export-graph --format json",
         ]
     )
@@ -879,9 +895,10 @@ def _build_subcommand_help(command: str) -> str:
                 "Refresh stale workflow Mermaid signatures without rewriting diagram bodies.",
                 "",
                 "Usage:",
-                "  logics-manager sync refresh-mermaid-signatures [args...]",
+                "  logics-manager sync refresh-mermaid-signatures [refs-or-paths...] [args...]",
                 "",
                 "Flags:",
+                "  --changed-only",
                 "  --format {text,json}",
                 "  --dry-run",
             ]
@@ -909,7 +926,7 @@ def _build_subcommand_help(command: str) -> str:
                 "Build a compact JSON context pack from workflow docs.",
                 "",
                 "Usage:",
-                "  logics-manager sync context-pack <ref> [args...]",
+                "  logics-manager sync context-pack <refs...> [args...]",
                 "",
                 "Flags:",
                 "  --mode {summary-only,diff-first,full}",
@@ -919,7 +936,7 @@ def _build_subcommand_help(command: str) -> str:
                 "  --dry-run",
                 "",
                 "Example:",
-                "  logics-manager sync context-pack req_001_my_request --out logics/context-pack.json",
+                "  logics-manager sync context-pack req_001_my_request task_002_fix_bug --out logics/context-pack.json",
             ]
         )
     if command == "read-doc":
@@ -1053,17 +1070,26 @@ def cmd_close_eligible_requests(args: argparse.Namespace) -> dict[str, object]:
 def cmd_refresh_mermaid_signatures(args: argparse.Namespace) -> dict[str, object]:
     repo_root = _find_repo_root(Path.cwd())
     modified: list[str] = []
-    for kind in ("request", "backlog", "task"):
-        directory = repo_root / DOC_KINDS[kind]["directory"]
-        for path in sorted(directory.glob("*.md")):
-            if refresh_workflow_mermaid_signature_file(path, kind, args.dry_run, repo_root=repo_root):
-                modified.append(path.relative_to(repo_root).as_posix())
+    if args.changed_only:
+        changed_sources = [
+            path
+            for path in _git_changed_paths(repo_root)
+            if path.startswith(("logics/request/", "logics/backlog/", "logics/tasks/")) and path.endswith(".md")
+        ]
+        targets = _resolve_target_docs(repo_root, changed_sources)
+    else:
+        targets = _resolve_target_docs(repo_root, args.sources)
+    for kind, path in targets:
+        if refresh_workflow_mermaid_signature_file(path, kind, args.dry_run, repo_root=repo_root):
+            modified.append(path.relative_to(repo_root).as_posix())
 
     payload = {
         "command": "sync",
         "kind": "refresh-mermaid-signatures",
         "repo_root": repo_root.as_posix(),
         "modified_files": modified,
+        "scanned_files": [path.relative_to(repo_root).as_posix() for _kind, path in targets],
+        "changed_only": args.changed_only,
         "dry_run": args.dry_run,
     }
     if args.format == "json":
@@ -1106,6 +1132,8 @@ def cmd_read_doc(args: argparse.Namespace) -> dict[str, object]:
         print(f"- path: {payload['path']}")
         print(f"- status: {payload['status']}")
         print(f"- truncated: {payload['truncated']}")
+        print("")
+        print(str(payload["content"]).rstrip())
     return {"command": "sync", "kind": "read-doc", "repo_root": repo_root.as_posix(), **payload}
 
 
@@ -1172,7 +1200,7 @@ def cmd_append_note(args: argparse.Namespace) -> dict[str, object]:
 
 def cmd_context_pack(args: argparse.Namespace) -> dict[str, object]:
     repo_root = _find_repo_root(Path.cwd())
-    payload = _build_context_pack(repo_root, args.ref, mode=args.mode, profile=args.profile, config=None)
+    payload = _build_context_pack(repo_root, ",".join(args.refs), mode=args.mode, profile=args.profile, config=None)
     if args.out:
         out_path, output_path = resolve_repo_output_path(repo_root, args.out)
         serialized = json.dumps(payload, indent=2, sort_keys=True) + "\n"
@@ -1188,7 +1216,7 @@ def cmd_context_pack(args: argparse.Namespace) -> dict[str, object]:
         if args.format == "json":
             print(json.dumps(payload, indent=2, sort_keys=True))
         else:
-            print(f"Context pack: {payload['ref']} ({payload['mode']}, {payload['profile']})")
+            print(f"Context pack: {', '.join(args.refs)} ({payload['mode']}, {payload['profile']})")
             print(f"- docs: {payload['estimates']['doc_count']}")
     return {"command": "sync", "kind": "context-pack", "repo_root": repo_root.as_posix(), **payload}