@grifhinz/logics-manager 2.2.0 → 2.3.0

package/logics_manager/flow.py

@@ -9,6 +9,9 @@ from pathlib import Path
 
 from .audit import audit_payload
 from .cli_output import print_payload
+from .flow_evidence import has_ac_proof as _has_ac_proof
+from .flow_evidence import has_validation_evidence as _has_validation_evidence
+from .flow_evidence import structured_validation_line as _structured_validation_line
 from .index import index_payload
 from .lint import expected_workflow_mermaid_signature, lint_payload
 from .path_utils import ensure_relative_to
@@ -974,19 +977,6 @@ def _section_has_checked_checkbox(text: str, heading: str) -> bool:
     return any("- [x]" in line.lower() for line in _section_lines(text.splitlines(), heading))
 
 
-def _has_validation_evidence(text: str) -> bool:
-    for line in _section_lines(text.splitlines(), "Validation"):
-        stripped = line.strip()
-        if not stripped.startswith("- "):
-            continue
-        value = stripped[2:].strip().lower()
-        if not value or value.startswith("run `") or value.startswith("run the "):
-            continue
-        if any(marker in value for marker in ("pass", "ok", "validated", "verification", "regression")):
-            return True
-    return False
-
-
 def _request_ac_ids(text: str) -> list[str]:
     ids: list[str] = []
     for line in _section_lines(text.splitlines(), "Acceptance criteria"):
@@ -996,11 +986,6 @@ def _request_ac_ids(text: str) -> list[str]:
     return ids
 
 
-def _has_ac_proof(text: str, ac_id: str) -> bool:
-    upper = text.upper()
-    return ac_id.upper() in upper and "proof:" in text.lower()
-
-
 def _first_product_path(repo_root: Path, product_ref: str) -> Path | None:
     path = repo_root / "logics" / "product" / f"{product_ref}.md"
     return path if path.is_file() else None
@@ -1254,7 +1239,16 @@ def _request_ac_entries(request_path: Path) -> list[tuple[str, str]]:
     return entries
 
 
-def repair_ac_traceability_payload(repo_root: Path, source: str, *, dry_run: bool) -> dict[str, object]:
+def _ac_traceability_entry(ac_id: str, target: str, text: str, proof: str | None, proof_source: str | None) -> str:
+    if proof and proof.strip():
+        rendered = f"request-{ac_id} -> {target}. Proof: {proof.strip()}"
+        if proof_source and proof_source.strip():
+            rendered += f" Source: `{proof_source.strip()}`"
+        return rendered
+    return f"request-{ac_id} -> {target}. Evidence needed: {text}"
+
+
+def repair_ac_traceability_payload(repo_root: Path, source: str, *, dry_run: bool, proof: str | None = None, proof_source: str | None = None) -> dict[str, object]:
     request_path = _resolve_workflow_source(repo_root, DOC_KINDS["request"], source)
     request_ref = request_path.stem
     ac_entries = _request_ac_entries(request_path)
@@ -1268,7 +1262,7 @@ def repair_ac_traceability_payload(repo_root: Path, source: str, *, dry_run: boo
     for item_path in linked_items:
         item_before = item_path.read_text(encoding="utf-8")
         item_missing = [
-            f"request-{ac_id} -> This backlog slice. Proof: {text}"
+            _ac_traceability_entry(ac_id, "This backlog slice", text, proof, proof_source)
             for ac_id, text in ac_entries
             if not _has_ac_proof(item_before, ac_id)
         ]
@@ -1285,7 +1279,7 @@ def repair_ac_traceability_payload(repo_root: Path, source: str, *, dry_run: boo
     for task_path in sorted(linked_task_paths):
         task_before = task_path.read_text(encoding="utf-8")
         task_missing = [
-            f"request-{ac_id} -> This task. Proof: {text}"
+            _ac_traceability_entry(ac_id, "This task", text, proof, proof_source)
             for ac_id, text in ac_entries
             if not _has_ac_proof(task_before, ac_id)
         ]
@@ -1296,6 +1290,8 @@ def repair_ac_traceability_payload(repo_root: Path, source: str, *, dry_run: boo
         "command": "repair",
         "kind": "ac-traceability",
         "source": request_path.relative_to(repo_root).as_posix(),
+        "proof_recorded": bool(proof and proof.strip()),
+        "proof_source": proof_source.strip() if proof_source and proof_source.strip() else None,
         "changed_files": sorted(path.as_posix() for path in changed_paths),
         "dry_run": dry_run,
     }
@@ -1423,7 +1419,7 @@ def _build_native_request_doc(repo_root: Path, planned_ref: str, title: str, arg
     references = [
         "`logics_manager/flow.py`",
         "`logics_manager/assist.py`",
-        "`python_tests/test_logics_manager_cli.py`",
+        "`tests/python/test_logics_manager_cli.py`",
     ]
     content = "\n".join(
         [
@@ -1862,6 +1858,7 @@ def _build_native_product_brief(
     related_backlog = f"`{backlog_ref}`" if backlog_ref else "(none yet)"
     related_task = f"`{task_ref}`" if task_ref else "(none yet)"
     related_architecture = ", ".join(f"`{item}`" for item in architecture_refs) if architecture_refs else "(none yet)"
+    signature_slug = _slugify(title) or "product-brief"
     content = "\n".join(
         [
             f"## {ref} - {title}",
@@ -1876,6 +1873,15 @@ def _build_native_product_brief(
             "# Overview",
             f"Logics should keep a single, predictable product surface for {title.lower()}.",
             "",
+            "```mermaid",
+            "%% logics-kind: product",
+            f"%% logics-signature: product|{signature_slug}|generated",
+            "flowchart TD",
+            "    Need[Product need] --> Scope[Scope and guardrails]",
+            "    Scope --> Decisions[Key decisions]",
+            "    Decisions --> Signals[Success signals]",
+            "```",
+            "",
             "# Goals",
             "- Keep the operator experience bounded and easy to reason about.",
             "- Preserve the CLI as the canonical workflow entrypoint.",
@@ -2235,24 +2241,30 @@ def build_parser() -> argparse.ArgumentParser:
 
     repair_gates = repair_sub.add_parser("gates", help="Check task and linked request gate checkboxes.")
     repair_gates.add_argument("source")
+    repair_gates.add_argument("--verify-closeout")
     repair_gates.add_argument("--format", choices=("text", "json"), default="text")
     repair_gates.add_argument("--dry-run", action="store_true")
     repair_gates.set_defaults(func=cmd_repair_gates)
 
     repair_ac = repair_sub.add_parser("ac-traceability", help="Add missing AC traceability entries.")
     repair_ac.add_argument("source")
+    repair_ac.add_argument("--proof")
+    repair_ac.add_argument("--proof-source")
+    repair_ac.add_argument("--verify-closeout")
     repair_ac.add_argument("--format", choices=("text", "json"), default="text")
     repair_ac.add_argument("--dry-run", action="store_true")
     repair_ac.set_defaults(func=cmd_repair_ac_traceability)
 
     repair_links = repair_sub.add_parser("links", help="Repair linked backlog/product references for a task.")
     repair_links.add_argument("source")
+    repair_links.add_argument("--verify-closeout")
     repair_links.add_argument("--format", choices=("text", "json"), default="text")
     repair_links.add_argument("--dry-run", action="store_true")
     repair_links.set_defaults(func=cmd_repair_links)
 
     repair_mermaid = repair_sub.add_parser("mermaid", help="Insert or refresh workflow Mermaid signatures.")
     repair_mermaid.add_argument("--refs", nargs="+", required=True)
+    repair_mermaid.add_argument("--verify-closeout")
     repair_mermaid.add_argument("--format", choices=("text", "json"), default="text")
     repair_mermaid.add_argument("--dry-run", action="store_true")
     repair_mermaid.set_defaults(func=cmd_repair_mermaid)
@@ -2260,6 +2272,9 @@ def build_parser() -> argparse.ArgumentParser:
     closeout_parser = sub.add_parser("closeout", help="Append validation, repair deterministic gaps, finish, and optionally validate/index.")
     closeout_parser.add_argument("source")
     closeout_parser.add_argument("--validation", action="append", default=[])
+    closeout_parser.add_argument("--validation-command")
+    closeout_parser.add_argument("--validation-result", default="passed")
+    closeout_parser.add_argument("--validation-note")
     closeout_parser.add_argument("--index", action="store_true")
     closeout_parser.add_argument("--lint", action="store_true")
     closeout_parser.add_argument("--audit", action="store_true")
@@ -2601,30 +2616,73 @@ def _print_repair_payload(payload: dict[str, object], output_format: str) -> Non
         print(f"- {rel_path}")
 
 
+REPAIR_VERIFY_CODES = {
+    "gates": {"task_gate_unchecked", "task_missing_done_gate", "request_dor_unchecked"},
+    "ac-traceability": {"ac_missing_item_traceability", "ac_missing_task_traceability"},
+    "links": {"backlog_missing_task_link", "companion_link_missing"},
+    "mermaid": {"mermaid_signature_stale"},
+}
+
+
+def _repair_verify_snapshot(repo_root: Path, source: str | None, dry_run: bool) -> dict[str, str]:
+    if dry_run or not source:
+        return {}
+    preflight = validate_closeout_payload(repo_root, source)
+    return _snapshot_existing_files(repo_root, list(preflight.get("related_paths", [])))
+
+
+def _finalize_repair_verify(repo_root: Path, payload: dict[str, object], source: str | None, snapshot: dict[str, str]) -> dict[str, object]:
+    if not source or payload.get("dry_run"):
+        return payload
+    preflight = validate_closeout_payload(repo_root, source)
+    payload["preflight"] = preflight
+    relevant_codes = REPAIR_VERIFY_CODES.get(str(payload.get("kind")), set())
+    remaining_relevant = [issue for issue in preflight.get("issues", []) if issue.get("code") in relevant_codes]
+    payload["rolled_back"] = False
+    if remaining_relevant and snapshot:
+        payload["attempted_changed_files"] = payload.get("changed_files", [])
+        _restore_file_snapshot(repo_root, snapshot)
+        payload["changed_files"] = []
+        payload["rolled_back"] = True
+        payload["rollback_reason"] = "repair verification left relevant closeout issues"
+        payload["remaining_relevant_issues"] = remaining_relevant
+    return payload
+
+
 def cmd_repair_gates(args: argparse.Namespace) -> dict[str, object]:
     repo_root = _find_repo_root(Path.cwd())
+    verify_source = args.verify_closeout or args.source
+    snapshot = _repair_verify_snapshot(repo_root, verify_source, args.dry_run)
     payload = repair_gates_payload(repo_root, args.source, dry_run=args.dry_run)
+    payload = _finalize_repair_verify(repo_root, payload, verify_source, snapshot)
     _print_repair_payload(payload, args.format)
     return payload
 
 
 def cmd_repair_ac_traceability(args: argparse.Namespace) -> dict[str, object]:
     repo_root = _find_repo_root(Path.cwd())
-    payload = repair_ac_traceability_payload(repo_root, args.source, dry_run=args.dry_run)
+    snapshot = _repair_verify_snapshot(repo_root, args.verify_closeout, args.dry_run)
+    payload = repair_ac_traceability_payload(repo_root, args.source, dry_run=args.dry_run, proof=args.proof, proof_source=args.proof_source)
+    payload = _finalize_repair_verify(repo_root, payload, args.verify_closeout, snapshot)
     _print_repair_payload(payload, args.format)
     return payload
 
 
 def cmd_repair_links(args: argparse.Namespace) -> dict[str, object]:
     repo_root = _find_repo_root(Path.cwd())
+    verify_source = args.verify_closeout or args.source
+    snapshot = _repair_verify_snapshot(repo_root, verify_source, args.dry_run)
     payload = repair_links_payload(repo_root, args.source, dry_run=args.dry_run)
+    payload = _finalize_repair_verify(repo_root, payload, verify_source, snapshot)
     _print_repair_payload(payload, args.format)
     return payload
 
 
 def cmd_repair_mermaid(args: argparse.Namespace) -> dict[str, object]:
     repo_root = _find_repo_root(Path.cwd())
+    snapshot = _repair_verify_snapshot(repo_root, args.verify_closeout, args.dry_run)
     payload = repair_mermaid_payload(repo_root, args.refs, dry_run=args.dry_run)
+    payload = _finalize_repair_verify(repo_root, payload, args.verify_closeout, snapshot)
     _print_repair_payload(payload, args.format)
     return payload
 
@@ -2642,11 +2700,43 @@ def _closeout_refs(repo_root: Path, task_path: Path) -> list[str]:
     return sorted(refs)
 
 
-def closeout_payload(repo_root: Path, source: str, *, validations: list[str], run_index: bool, run_lint: bool, run_audit: bool, dry_run: bool) -> dict[str, object]:
+def _snapshot_existing_files(repo_root: Path, rel_paths: list[str]) -> dict[str, str]:
+    snapshot: dict[str, str] = {}
+    for rel_path in rel_paths:
+        path = repo_root / rel_path
+        if path.is_file():
+            snapshot[rel_path] = path.read_text(encoding="utf-8")
+    return snapshot
+
+
+def _restore_file_snapshot(repo_root: Path, snapshot: dict[str, str]) -> None:
+    for rel_path, content in snapshot.items():
+        path = repo_root / rel_path
+        path.write_text(content, encoding="utf-8")
+
+
+def closeout_payload(
+    repo_root: Path,
+    source: str,
+    *,
+    validations: list[str],
+    run_index: bool,
+    run_lint: bool,
+    run_audit: bool,
+    dry_run: bool,
+    validation_command: str | None = None,
+    validation_result: str = "passed",
+    validation_note: str | None = None,
+) -> dict[str, object]:
     task_path = _resolve_workflow_source(repo_root, DOC_KINDS["task"], source)
     task_ref = task_path.stem
     changed_files: set[str] = set()
     steps: list[dict[str, object]] = []
+    initial_preflight = validate_closeout_payload(repo_root, task_ref)
+    rollback_snapshot = {} if dry_run else _snapshot_existing_files(repo_root, list(initial_preflight.get("related_paths", [])))
+
+    if validation_command and validation_command.strip():
+        validations = [*validations, _structured_validation_line(validation_command, validation_result, validation_note)]
 
     for validation in validations:
         if validation and validation.strip():
@@ -2678,12 +2768,20 @@ def closeout_payload(repo_root: Path, source: str, *, validations: list[str], ru
 
     preflight = validate_closeout_payload(repo_root, task_ref)
     if preflight["issues"]:
+        rolled_back = False
+        attempted_changed_files = sorted(changed_files)
+        if rollback_snapshot:
+            _restore_file_snapshot(repo_root, rollback_snapshot)
+            changed_files.clear()
+            rolled_back = True
         return {
             "command": "closeout",
             "ok": False,
             "source": task_path.relative_to(repo_root).as_posix(),
             "changed_files": sorted(changed_files),
+            "attempted_changed_files": attempted_changed_files,
             "preflight": preflight,
+            "rolled_back": rolled_back,
             "steps": steps,
             "dry_run": dry_run,
         }
@@ -2736,6 +2834,7 @@ def closeout_payload(repo_root: Path, source: str, *, validations: list[str], ru
         "lint": lint_result,
         "audit": audit_result,
         "steps": steps,
+        "rolled_back": False,
         "dry_run": dry_run,
     }
 
@@ -2746,6 +2845,9 @@ def cmd_closeout(args: argparse.Namespace) -> dict[str, object]:
         repo_root,
         args.source,
         validations=args.validation or [],
+        validation_command=args.validation_command,
+        validation_result=args.validation_result,
+        validation_note=args.validation_note,
         run_index=args.index,
         run_lint=args.lint,
         run_audit=args.audit,

package/logics_manager/flow_evidence.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from datetime import date
+import re
+
+
+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 has_validation_evidence(text: str) -> bool:
+    concrete_ok_context = ("lint", "audit", "test", "pytest", "npm", "ci", "coverage", "smoke", "package")
+    invalid_markers = ("...", "todo", "tbd", "pending", "needs ", "need ", "not ok", "failed", "failure", "failing")
+    for line in section_lines(text.splitlines(), "Validation"):
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        value = stripped[2:].strip().lower()
+        if not value or value.startswith("run `") or value.startswith("run the "):
+            continue
+        if any(marker in value for marker in invalid_markers):
+            continue
+        if "command:" in value and "result:" in value and ("date:" in value or "session:" in value):
+            result_match = re.search(r"\bresult:\s*([^|,;]+)", value)
+            result = result_match.group(1).strip() if result_match else ""
+            if result in {"pass", "passed", "ok", "success", "succeeded"}:
+                return True
+        if any(marker in value for marker in ("pass", "validated", "verified", "verification", "regression")):
+            return True
+        if "ok" in value and any(marker in value for marker in concrete_ok_context):
+            return True
+    return False
+
+
+def has_ac_proof(text: str, ac_id: str) -> bool:
+    upper = text.upper()
+    return ac_id.upper() in upper and "proof:" in text.lower()
+
+
+def structured_validation_line(command: str, result: str, note: str | None) -> str:
+    normalized_result = result.strip().lower() or "passed"
+    parts = [
+        f"command: `{command.strip()}`",
+        f"result: {normalized_result}",
+        f"date: {date.today().isoformat()}",
+    ]
+    if note and note.strip():
+        parts.append(f"note: {note.strip()}")
+    return " | ".join(parts)

package/logics_manager/update_check.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import time
+from typing import Any, Callable
+from urllib.error import URLError
+from urllib.request import urlopen
+
+
+NPM_LATEST_URL = "https://registry.npmjs.org/@grifhinz%2Flogics-manager/latest"
+DISABLE_ENV = "LOGICS_MANAGER_NO_UPDATE_CHECK"
+CHECK_INTERVAL_SECONDS = 24 * 60 * 60
+
+
+@dataclass(frozen=True)
+class UpdateInfo:
+    current_version: str
+    latest_version: str | None
+    update_available: bool
+    checked_at: int | None
+    update_command: str
+    source: str
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "currentVersion": self.current_version,
+            "latestVersion": self.latest_version,
+            "updateAvailable": self.update_available,
+            "checkedAt": self.checked_at,
+            "updateCommand": self.update_command,
+            "source": self.source,
+        }
+
+
+def _parse_version(value: str | None) -> tuple[int, int, int, str]:
+    raw = (value or "").strip().lstrip("v")
+    parts = raw.split(".", 3)
+    numeric: list[int] = []
+    suffix = ""
+    for index, part in enumerate(parts[:3]):
+        digits = ""
+        rest = ""
+        for char in part:
+            if char.isdigit() and not rest:
+                digits += char
+            else:
+                rest += char
+        numeric.append(int(digits or "0"))
+        if rest:
+            suffix = ".".join([rest, *parts[index + 1 :]])
+            break
+    while len(numeric) < 3:
+        numeric.append(0)
+    return numeric[0], numeric[1], numeric[2], suffix
+
+
+def is_newer_version(latest: str | None, current: str | None) -> bool:
+    latest_tuple = _parse_version(latest)
+    current_tuple = _parse_version(current)
+    return latest_tuple[:3] > current_tuple[:3]
+
+
+def update_cache_path() -> Path:
+    override = os.environ.get("LOGICS_MANAGER_UPDATE_CACHE")
+    if override:
+        return Path(override)
+    cache_root = os.environ.get("XDG_CACHE_HOME")
+    if cache_root:
+        return Path(cache_root) / "logics-manager" / "update-check.json"
+    return Path.home() / ".cache" / "logics-manager" / "update-check.json"
+
+
+def _read_cache(path: Path, now: int) -> dict[str, Any] | None:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    checked_at = int(payload.get("checked_at") or 0)
+    if checked_at <= 0 or now - checked_at > CHECK_INTERVAL_SECONDS:
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _write_cache(path: Path, payload: dict[str, Any]) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(payload, sort_keys=True), encoding="utf-8")
+    except OSError:
+        return
+
+
+def fetch_latest_npm_version(*, timeout: float = 0.75, opener: Callable[..., Any] = urlopen) -> str | None:
+    try:
+        with opener(NPM_LATEST_URL, timeout=timeout) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except (OSError, URLError, TimeoutError, json.JSONDecodeError, ValueError):
+        return None
+    version = payload.get("version") if isinstance(payload, dict) else None
+    return version.strip() if isinstance(version, str) and version.strip() else None
+
+
+def get_update_info(
+    current_version: str,
+    *,
+    cache_path: Path | None = None,
+    now: int | None = None,
+    fetch_latest: Callable[[], str | None] | None = None,
+) -> UpdateInfo:
+    now_value = int(time.time() if now is None else now)
+    path = cache_path or update_cache_path()
+    cached = _read_cache(path, now_value)
+    latest = str(cached.get("latest_version") or "") if cached else ""
+    if not latest:
+        latest = (fetch_latest or fetch_latest_npm_version)() or ""
+        _write_cache(path, {"checked_at": now_value, "latest_version": latest})
+    return UpdateInfo(
+        current_version=current_version,
+        latest_version=latest or None,
+        update_available=is_newer_version(latest, current_version),
+        checked_at=now_value,
+        update_command="logics-manager self-update",
+        source="npm",
+    )
+
+
+def get_update_notice(current_version: str) -> str | None:
+    if os.environ.get(DISABLE_ENV):
+        return None
+    info = get_update_info(current_version)
+    if not info.update_available or not info.latest_version:
+        return None
+    return (
+        f"logics-manager {info.latest_version} is available "
+        f"(current {info.current_version}). Run `{info.update_command}` to update."
+    )