@grifhinz/logics-manager 2.6.0 → 2.8.0

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(
         [
@@ -800,6 +827,8 @@ def _workflow_mermaid_block(kind: str, signature: str) -> list[str]:
 
 
 def _with_workflow_mermaid_overview(kind: str, content: str) -> str:
+    if kind == "task":
+        return content
     lines = content.rstrip().splitlines()
     signature = expected_workflow_mermaid_signature(kind, lines)
     if not signature:
@@ -995,6 +1024,8 @@ def _mermaid_closeout_issue(path: Path, kind: str) -> str | None:
     text = path.read_text(encoding="utf-8")
     match = re.search(r"```mermaid\s*\n(.*?)\n```", text, flags=re.DOTALL)
     if match is None:
+        if kind == "task":
+            return None
         return "missing Mermaid overview block"
     signature_match = re.search(r"^\s*%%\s*logics-signature:\s*(.+?)\s*$", match.group(1), flags=re.MULTILINE)
     expected = expected_workflow_mermaid_signature(kind, text.splitlines())
@@ -1625,7 +1656,7 @@ def _build_native_task_doc(
             "",
         ]
     ).rstrip() + "\n"
-    return _with_workflow_mermaid_overview("task", content)
+    return content
 
 
 def _extract_doc_title(path: Path) -> str:
@@ -2183,7 +2214,7 @@ def _build_native_task_from_backlog(
             "",
         ]
     ).rstrip() + "\n"
-    return ref, _with_workflow_mermaid_overview("task", content)
+    return ref, content
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -2210,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"):
@@ -2425,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(
@@ -2789,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))
@@ -3240,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
@@ -3285,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/lint.py

@@ -15,18 +15,19 @@ from .config import find_repo_root
 @dataclass(frozen=True)
 class Kind:
     directory: str
-    prefix: str
+    prefixes: tuple[str, ...]
     requires_progress: bool
     required_indicators: tuple[str, ...]
     allowed_statuses: tuple[str, ...]
 
 
 KINDS = {
-    "request": Kind("logics/request", "req", False, ("From version", "Understanding", "Confidence"), ("Draft", "Ready", "In progress", "Blocked", "Done", "Obsolete", "Archived")),
-    "backlog": Kind("logics/backlog", "item", True, ("From version", "Understanding", "Confidence", "Progress"), ("Draft", "Ready", "In progress", "Blocked", "Done", "Obsolete", "Archived")),
-    "task": Kind("logics/tasks", "task", True, ("From version", "Understanding", "Confidence", "Progress"), ("Draft", "Ready", "In progress", "Blocked", "Done", "Obsolete", "Archived")),
-    "product": Kind("logics/product", "prod", False, ("Date", "Status", "Related request", "Related backlog", "Related task", "Related architecture", "Reminder"), ("Draft", "Proposed", "Active", "Accepted", "Validated", "Rejected", "Superseded", "Settled", "Archived")),
-    "architecture": Kind("logics/architecture", "adr", False, ("Date", "Status", "Drivers", "Related request", "Related backlog", "Related task", "Reminder"), ("Draft", "Proposed", "Accepted", "Validated", "Rejected", "Superseded", "Settled", "Archived")),
+    "request": Kind("logics/request", ("req",), False, ("From version", "Understanding", "Confidence"), ("Draft", "Ready", "In progress", "Blocked", "Done", "Obsolete", "Archived")),
+    "backlog": Kind("logics/backlog", ("item",), True, ("From version", "Understanding", "Confidence", "Progress"), ("Draft", "Ready", "In progress", "Blocked", "Done", "Obsolete", "Archived")),
+    "task": Kind("logics/tasks", ("task",), True, ("From version", "Understanding", "Confidence", "Progress"), ("Draft", "Ready", "In progress", "Blocked", "Done", "Obsolete", "Archived")),
+    "product": Kind("logics/product", ("prod",), False, ("Date", "Status", "Related request", "Related backlog", "Related task", "Related architecture", "Reminder"), ("Draft", "Proposed", "Active", "Accepted", "Validated", "Rejected", "Superseded", "Settled", "Archived")),
+    "architecture": Kind("logics/architecture", ("adr",), False, ("Date", "Status", "Drivers", "Related request", "Related backlog", "Related task", "Reminder"), ("Draft", "Proposed", "Accepted", "Validated", "Rejected", "Superseded", "Settled", "Archived")),
+    "spec": Kind("logics/specs", ("spec", "req"), False, ("From version", "Status", "Understanding", "Confidence"), ("Draft", "Ready", "In progress", "Done", "Validated", "Settled", "Archived")),
 }
 
 WORKFLOW_KINDS = {"request", "backlog", "task"}
@@ -503,7 +504,8 @@ def _lint_file(path: Path, kind_name: str, kind: Kind, require_status: bool, che
     issues: list[str] = []
     warnings: list[str] = []
     name = path.name
-    if not re.match(rf"^{re.escape(kind.prefix)}_\d{{3}}_[a-z0-9_]+\.md$", name):
+    allowed_prefixes = "|".join(re.escape(prefix) for prefix in kind.prefixes)
+    if not re.match(rf"^({allowed_prefixes})_\d{{3}}_[a-z0-9_]+\.md$", name):
         issues.append(f"bad filename: {name}")
 
     lines = _read_lines(path)
@@ -557,6 +559,8 @@ def lint_payload(repo_root: Path, *, require_status: bool = False) -> dict[str,
         if not directory.is_dir():
             continue
         for path in sorted(directory.glob("*.md")):
+            if path.name == "README.md":
+                continue
             rel_path = path.relative_to(repo_root)
             issues, warnings = _lint_file(
                 path,

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}