agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/command_queue_contract.py

@@ -0,0 +1,161 @@
+"""Machine-readable command queue state contract for GUI readiness.
+
+The contract is intentionally read-only. It classifies the repo-backed
+agent command inbox without executing, deleting, staging, or committing files.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import json
+import subprocess
+
+QUEUE_NO_COMMAND = "NO_COMMAND"
+QUEUE_EXACTLY_ONE_COMMAND = "EXACTLY_ONE_COMMAND"
+QUEUE_MULTIPLE_COMMANDS = "MULTIPLE_COMMANDS"
+QUEUE_ALREADY_EXECUTED_COMMAND = "ALREADY_EXECUTED_COMMAND"
+QUEUE_DIRTY_INBOX = "DIRTY_INBOX"
+QUEUE_MISSING_METADATA = "MISSING_COMMAND_METADATA"
+QUEUE_INCOMPLETE_COMMAND = "INCOMPLETE_COMMAND"
+
+COMMAND_DIR = Path(".agentic/commands")
+INBOX_DIR = COMMAND_DIR / "inbox"
+EXECUTED_JSONL = COMMAND_DIR / "executed.jsonl"
+
+@dataclass(frozen=True)
+class QueueCommandCandidate:
+    command_id: str | None
+    stem: str
+    yaml_path: str
+    script_path: str
+    has_yaml: bool
+    has_script: bool
+
+@dataclass(frozen=True)
+class QueueState:
+    schema_version: int
+    queue_state: str
+    valid_for_agent_next: bool
+    command_count: int
+    candidates: tuple[QueueCommandCandidate, ...]
+    dirty_paths: tuple[str, ...]
+    reason: str
+    next_allowed_actions: tuple[str, ...]
+
+def _root(root: Path) -> Path:
+    return root.resolve()
+
+def _parse_simple_yaml(path: Path) -> dict[str, str]:
+    data: dict[str, str] = {}
+    if not path.exists():
+        return data
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        value = value.strip()
+        if (value.startswith(chr(34)) and value.endswith(chr(34))) or (value.startswith(chr(39)) and value.endswith(chr(39))):
+            value = value[1:-1]
+        data[key.strip()] = value
+    return data
+
+def _executed_ids(root: Path) -> set[str]:
+    path = _root(root) / EXECUTED_JSONL
+    if not path.exists():
+        return set()
+    ids: set[str] = set()
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        if not raw.strip():
+            continue
+        try:
+            item = json.loads(raw)
+        except json.JSONDecodeError:
+            continue
+        command_id = item.get("command_id")
+        if isinstance(command_id, str):
+            ids.add(command_id)
+    return ids
+
+def _dirty_inbox_paths(root: Path) -> tuple[str, ...]:
+    proc = subprocess.run(["git", "status", "--porcelain", ".agentic/commands/inbox"], cwd=_root(root), text=True, capture_output=True, check=False)
+    if proc.returncode != 0:
+        return ()
+    paths: list[str] = []
+    for raw in proc.stdout.splitlines():
+        if raw.strip():
+            paths.append(raw[3:])
+    return tuple(paths)
+
+def _candidates(root: Path) -> tuple[QueueCommandCandidate, ...]:
+    inbox = _root(root) / INBOX_DIR
+    if not inbox.exists():
+        return ()
+    stems = {path.stem for path in inbox.glob("*.yaml")} | {path.stem for path in inbox.glob("*.sh")}
+    result: list[QueueCommandCandidate] = []
+    for stem in sorted(stems):
+        yaml_path = inbox / f"{stem}.yaml"
+        script_path = inbox / f"{stem}.sh"
+        data = _parse_simple_yaml(yaml_path)
+        command_id = data.get("command_id") or None
+        result.append(QueueCommandCandidate(command_id, stem, yaml_path.relative_to(_root(root)).as_posix(), script_path.relative_to(_root(root)).as_posix(), yaml_path.exists(), script_path.exists()))
+    return tuple(result)
+
+def inspect_queue_state(root: Path = Path(".")) -> QueueState:
+    root = _root(root)
+    dirty = _dirty_inbox_paths(root)
+    candidates = _candidates(root)
+    complete = tuple(item for item in candidates if item.has_yaml and item.has_script)
+    incomplete = tuple(item for item in candidates if not (item.has_yaml and item.has_script))
+    executed = _executed_ids(root)
+    already = tuple(item for item in complete if item.command_id in executed)
+    missing_meta = tuple(item for item in complete if not item.command_id)
+    if dirty:
+        state = QUEUE_DIRTY_INBOX
+        reason = "command inbox has uncommitted changes"
+    elif incomplete:
+        state = QUEUE_INCOMPLETE_COMMAND
+        reason = "command inbox contains unmatched yaml or shell file"
+    elif not complete:
+        state = QUEUE_NO_COMMAND
+        reason = "no complete pending command pair"
+    elif len(complete) > 1:
+        state = QUEUE_MULTIPLE_COMMANDS
+        reason = "multiple complete pending command pairs"
+    elif missing_meta:
+        state = QUEUE_MISSING_METADATA
+        reason = "pending command is missing command_id metadata"
+    elif already:
+        state = QUEUE_ALREADY_EXECUTED_COMMAND
+        reason = "pending command_id is already recorded as executed"
+    else:
+        state = QUEUE_EXACTLY_ONE_COMMAND
+        reason = "exactly one complete pending command pair is ready"
+    valid = state == QUEUE_EXACTLY_ONE_COMMAND
+    next_actions = ("agent-next",) if valid else ("cockpit.actions",)
+    return QueueState(1, state, valid, len(complete), candidates, dirty, reason, next_actions)
+
+def queue_state_as_json_data(state: QueueState) -> dict[str, object]:
+    return {
+        "schema_version": state.schema_version,
+        "queue_state": state.queue_state,
+        "valid_for_agent_next": state.valid_for_agent_next,
+        "command_count": state.command_count,
+        "dirty_paths": list(state.dirty_paths),
+        "reason": state.reason,
+        "next_allowed_actions": list(state.next_allowed_actions),
+        "candidates": [
+            {
+                "command_id": item.command_id,
+                "stem": item.stem,
+                "yaml_path": item.yaml_path,
+                "script_path": item.script_path,
+                "has_yaml": item.has_yaml,
+                "has_script": item.has_script,
+            }
+            for item in state.candidates
+        ],
+    }

agentic_project_kit/command_selector.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from agentic_project_kit.command_manifest import SURFACE_VALUES
+
+
+SAFETY_SORT_ORDER = {"READ_ONLY": 0, "BOUNDED": 1, "DESTRUCTIVE": 2}
+SURFACE_SORT_ORDER = {"orchestrator": 0, "diagnostic": 1, "primitive": 2}
+DIAGNOSTIC_SURFACE_SORT_ORDER = {"diagnostic": 0, "orchestrator": 1, "primitive": 2}
+DIAGNOSTIC_TASK_TERMS = (
+    "audit",
+    "check",
+    "diagnose",
+    "diagnostic",
+    "doctor",
+    "inspect",
+    "list",
+    "readiness",
+    "report",
+    "show",
+    "status",
+    "validate",
+)
+
+
+@dataclass(frozen=True)
+class CommandSelection:
+    status: str
+    payload: dict[str, Any]
+
+
+def normalize_raw_command(command_line: str) -> str:
+    """Normalize a pasted shell command for deterministic manifest lookup."""
+    text = command_line.strip()
+    while text and text[0] in "$#>":
+        text = text[1:].lstrip()
+    return " ".join(text.split())
+
+
+def _matches_prefix(command_line: str, prefix: str) -> bool:
+    return command_line == prefix or command_line.startswith(prefix + " ")
+
+
+def _command_summary(command: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "qualified_name": str(command.get("qualified_name") or ""),
+        "safety": str(command.get("safety") or ""),
+        "surface": str(command.get("surface") or ""),
+        "when_to_use": str(command.get("when_to_use") or ""),
+        "dry_run_available": bool(command.get("dry_run_available")),
+    }
+
+
+def _invalid_surface_summaries(commands: list[dict[str, Any]]) -> list[dict[str, str]]:
+    invalid = []
+    for command in commands:
+        surface = str(command.get("surface") or "")
+        if surface not in SURFACE_VALUES:
+            invalid.append(
+                {
+                    "qualified_name": str(command.get("qualified_name") or ""),
+                    "surface": surface,
+                }
+            )
+    return invalid
+
+
+def _surface_sort_order(task_tag: str) -> dict[str, int]:
+    normalized = task_tag.casefold()
+    if any(term in normalized for term in DIAGNOSTIC_TASK_TERMS):
+        return DIAGNOSTIC_SURFACE_SORT_ORDER
+    return SURFACE_SORT_ORDER
+
+
+def select_for_raw(manifest: dict[str, Any], command_line: str) -> CommandSelection:
+    normalized = normalize_raw_command(command_line)
+    matches: list[tuple[str, dict[str, Any]]] = []
+    for command in manifest.get("commands") or []:
+        if not isinstance(command, dict):
+            continue
+        for raw_prefix in command.get("replaces_raw") or []:
+            prefix = normalize_raw_command(str(raw_prefix))
+            if prefix and _matches_prefix(normalized, prefix):
+                matches.append((prefix, command))
+
+    if not matches:
+        return CommandSelection(
+            status="no_match",
+            payload={
+                "mode": "raw",
+                "status": "no_match",
+                "raw": command_line,
+                "normalized_raw": normalized,
+                "message": "no mapping; if this mutates the repo, check the manifest before running raw",
+            },
+        )
+
+    longest = max(len(prefix) for prefix, _command in matches)
+    selected = [
+        command for prefix, command in matches if len(prefix) == longest
+    ]
+    invalid = _invalid_surface_summaries(selected)
+    if invalid:
+        return CommandSelection(
+            status="invalid_manifest",
+            payload={
+                "mode": "raw",
+                "status": "invalid_manifest",
+                "raw": command_line,
+                "normalized_raw": normalized,
+                "invalid_surfaces": invalid,
+            },
+        )
+    selected.sort(
+        key=lambda command: (
+            SAFETY_SORT_ORDER.get(str(command.get("safety") or ""), 99),
+            SURFACE_SORT_ORDER.get(str(command.get("surface") or ""), 99),
+            str(command.get("qualified_name") or ""),
+        )
+    )
+    matched_prefix = sorted({prefix for prefix, _command in matches if len(prefix) == longest})[0]
+    return CommandSelection(
+        status="match",
+        payload={
+            "mode": "raw",
+            "status": "match",
+            "raw": command_line,
+            "normalized_raw": normalized,
+            "matched_prefix": matched_prefix,
+            "commands": [_command_summary(command) for command in selected],
+        },
+    )
+
+
+def _all_task_tags(manifest: dict[str, Any]) -> list[str]:
+    tags: set[str] = set()
+    for command in manifest.get("commands") or []:
+        if not isinstance(command, dict):
+            continue
+        tags.update(str(tag) for tag in command.get("task_tags") or [] if str(tag).strip())
+    return sorted(tags)
+
+
+def select_for_task(manifest: dict[str, Any], task_tag: str) -> CommandSelection:
+    commands = [
+        command
+        for command in manifest.get("commands") or []
+        if isinstance(command, dict) and task_tag in set(command.get("task_tags") or [])
+    ]
+    if not commands:
+        return CommandSelection(
+            status="unknown_tag",
+            payload={
+                "mode": "task",
+                "status": "unknown_tag",
+                "task_tag": task_tag,
+                "available_tags": _all_task_tags(manifest),
+            },
+        )
+
+    invalid = _invalid_surface_summaries(commands)
+    if invalid:
+        return CommandSelection(
+            status="invalid_manifest",
+            payload={
+                "mode": "task",
+                "status": "invalid_manifest",
+                "task_tag": task_tag,
+                "invalid_surfaces": invalid,
+            },
+        )
+
+    surface_order = _surface_sort_order(task_tag)
+    commands.sort(
+        key=lambda command: (
+            SAFETY_SORT_ORDER.get(str(command.get("safety") or ""), 99),
+            surface_order.get(str(command.get("surface") or ""), 99),
+            str(command.get("qualified_name") or ""),
+        )
+    )
+    return CommandSelection(
+        status="match",
+        payload={
+            "mode": "task",
+            "status": "match",
+            "task_tag": task_tag,
+            "commands": [_command_summary(command) for command in commands],
+        },
+    )
+
+
+def render_command_selection(selection: CommandSelection) -> str:
+    payload = selection.payload
+    if payload["mode"] == "raw":
+        lines = [
+            "COMMAND_FOR",
+            f"STATUS={payload['status']}",
+            f"RAW={payload['raw']}",
+            f"NORMALIZED_RAW={payload['normalized_raw']}",
+        ]
+        if payload["status"] == "no_match":
+            lines.append(str(payload["message"]))
+            return "\n".join(lines) + "\n"
+        if payload["status"] == "invalid_manifest":
+            for invalid in payload["invalid_surfaces"]:
+                lines.append(
+                    "INVALID_SURFACE="
+                    f"{invalid['qualified_name']} | surface={invalid['surface']}"
+                )
+            return "\n".join(lines) + "\n"
+        lines.append(f"MATCHED_PREFIX={payload['matched_prefix']}")
+        for command in payload["commands"]:
+            dry_run = "yes" if command["dry_run_available"] else "no"
+            lines.append(
+                "WRAPPER="
+                f"{command['qualified_name']} | safety={command['safety']} | "
+                f"surface={command['surface']} | "
+                f"dry_run_available={dry_run} | when_to_use={command['when_to_use']}"
+            )
+        return "\n".join(lines) + "\n"
+
+    lines = [
+        "COMMAND_FOR",
+        f"STATUS={payload['status']}",
+        f"TASK_TAG={payload['task_tag']}",
+    ]
+    if payload["status"] == "unknown_tag":
+        lines.append("AVAILABLE_TAGS=" + ", ".join(payload["available_tags"]))
+        return "\n".join(lines) + "\n"
+    if payload["status"] == "invalid_manifest":
+        for invalid in payload["invalid_surfaces"]:
+            lines.append(
+                "INVALID_SURFACE="
+                f"{invalid['qualified_name']} | surface={invalid['surface']}"
+            )
+        return "\n".join(lines) + "\n"
+    for command in payload["commands"]:
+        lines.append(
+            f"COMMAND={command['qualified_name']} | safety={command['safety']} | "
+            f"surface={command['surface']} | "
+            f"when_to_use={command['when_to_use']}"
+        )
+    return "\n".join(lines) + "\n"

agentic_project_kit/command_taxonomy.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import json
+from pathlib import Path
+from typing import Any
+
+from agentic_project_kit.workspace import LEGACY_DEFAULTS, load_workspace
+
+ALLOWED_COMMAND_CATEGORIES: tuple[str, ...] = (
+    "core",
+    "transfer",
+    "audit",
+    "release",
+    "handoff",
+    "gui-readiness",
+    "diagnostic",
+    "docs",
+    "workflow",
+    "governance",
+    "state",
+    "work-order",
+    "advanced/internal",
+)
+
+COMMAND_REFERENCE_PATH = Path(LEGACY_DEFAULTS.reference_root) / "agentic-kit-commands.json"
+
+
+@dataclass(frozen=True)
+class CommandTaxonomyEntry:
+    qualified_name: str
+    group: str
+    category: str
+    role: str
+    composition_level: str
+    recommendation_weight: int
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class CommandTaxonomyReport:
+    command_count: int
+    entries: tuple[CommandTaxonomyEntry, ...]
+    findings: tuple[str, ...]
+
+    @property
+    def ok(self) -> bool:
+        return not self.findings
+
+    @property
+    def status(self) -> str:
+        return "PASS" if self.ok else "FAIL"
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "schema_version": 1,
+            "kind": "command_taxonomy_report",
+            "status": self.status,
+            "command_count": self.command_count,
+            "category_count": len({entry.category for entry in self.entries}),
+            "findings": list(self.findings),
+            "entries": [entry.as_dict() for entry in self.entries],
+        }
+
+
+def load_command_reference(project_root: Path) -> list[dict[str, Any]]:
+    path = load_workspace(project_root).reference_file("agentic-kit-commands.json")
+    data = json.loads(path.read_text(encoding="utf-8"))
+    commands = data.get("commands") if isinstance(data, dict) else data
+    if not isinstance(commands, list):
+        raise ValueError(f"Unsupported command reference shape in {path}")
+    return [command for command in commands if isinstance(command, dict)]
+
+
+def classify_command(command: dict[str, Any]) -> CommandTaxonomyEntry:
+    qualified = str(command.get("qualified_name") or command.get("name") or "")
+    group = str(command.get("group") or "")
+    path = command.get("path")
+    path_parts = tuple(str(part) for part in path) if isinstance(path, list) else ()
+    leaf = path_parts[-1] if path_parts else qualified.rsplit(" ", 1)[-1]
+
+    category = _category_for(group, leaf, qualified)
+    composition_level = _composition_level_for(group, leaf, qualified)
+    recommendation_weight = _recommendation_weight_for(category, composition_level, qualified)
+    role = _role_for(category, leaf, qualified, composition_level=composition_level)
+    return CommandTaxonomyEntry(
+        qualified_name=qualified,
+        group=group,
+        category=category,
+        role=role,
+        composition_level=composition_level,
+        recommendation_weight=recommendation_weight,
+    )
+
+
+def _category_for(group: str, leaf: str, qualified: str) -> str:
+    if group == "transfer" or qualified.startswith("agentic-kit transfer "):
+        return "transfer"
+    if group in {"handoff", "boot"} or "handoff" in qualified:
+        return "handoff"
+    if group in {"rules", "rule-registry", "governance"}:
+        return "governance"
+    if group in {"workflow", "workflow-guard"}:
+        return "workflow"
+    if group == "state":
+        return "state"
+    if group == "work-order":
+        return "work-order"
+    if group == "workspace":
+        return "core"
+    if group in {"evidence", "actions", "patterns", "pass-already-done", "dev"}:
+        return "advanced/internal"
+    if group == "todo":
+        return "core"
+    if group == "cockpit":
+        return "gui-readiness"
+
+    if leaf.startswith("audit-") or leaf.endswith("-audit"):
+        return "audit"
+    if group == "direction":
+        return "docs"
+    if leaf in {"docs-audit", "docs-registry", "doc-mesh-repair", "project-direction"} or leaf.startswith("doc-"):
+        return "docs"
+    if leaf in {"release-publish", "release-prep", "post-release-check", "release-metadata-authority-gate"}:
+        return "release"
+    if leaf == "gui-readiness-gate":
+        return "gui-readiness"
+    if leaf in {"doctor", "check", "check-docs", "check-todo", "standard-gates-audit-suite", "command-taxonomy-check", "patch-preflight", "patch-scope-preflight"}:
+        return "diagnostic"
+    if group in {"root", "scaffold"}:
+        return "core"
+    return "advanced/internal"
+
+
+PREFERRED_COMPOSITE_COMMANDS: tuple[str, ...] = (
+    "agentic-kit transfer pr-closeout-complete",
+    "agentic-kit transfer post-merge-settle",
+    "agentic-kit transfer post-merge-complete",
+    "agentic-kit transfer pr-create-complete",
+    "agentic-kit work start",
+    "agentic-kit work check",
+    "agentic-kit work finish",
+    "agentic-kit work recover",
+    "agentic-kit release ready",
+    "agentic-kit release prepare",
+    "agentic-kit release-publish",
+)
+
+
+def _composition_level_for(group: str, leaf: str, qualified: str) -> str:
+    if qualified in PREFERRED_COMPOSITE_COMMANDS:
+        return "composite"
+    if leaf in {
+        "pr-closeout-complete",
+        "post-merge-settle",
+        "post-merge-complete",
+        "pr-create-complete",
+        "patch-cycle-status",
+        "standard-gates-audit-suite",
+    }:
+        return "composite"
+    if group in {"actions", "dev", "evidence", "patterns"}:
+        return "elementary/internal"
+    return "elementary"
+
+
+def _recommendation_weight_for(category: str, composition_level: str, qualified: str) -> int:
+    if qualified == "agentic-kit transfer pr-closeout-complete":
+        return 100
+    if composition_level == "composite":
+        return 90
+    if category == "advanced/internal" or composition_level == "elementary/internal":
+        return 20
+    return 50
+
+
+
+def _role_for(category: str, leaf: str, qualified: str, *, composition_level: str = "elementary") -> str:
+    if category == "audit":
+        return "Runs a focused repository safety or consistency audit."
+    if category == "transfer":
+        if composition_level == "composite":
+            return "Preferred high-level wrapper for guarded transfer or PR lifecycle workflows; LLMs should choose this before low-level commands."
+        return "Supports guarded GitHub/local transfer and PR lifecycle workflows."
+    if category == "release":
+        return "Supports release preparation, verification, or controlled publishing."
+    if category == "gui-readiness":
+        return "Supports GUI gatekeeper readiness or cockpit workflows."
+    if category == "docs":
+        return "Maintains documentation coverage, lifecycle, or mesh consistency."
+    if category == "diagnostic":
+        return "Summarizes health, taxonomy, preflight, or standard gate state."
+    if category == "handoff":
+        return "Supports successor-chat handoff and bootstrap continuity."
+    if category == "governance":
+        return "Maintains rules, policy, or governance state."
+    if category == "workflow":
+        return "Runs workflow planning or guard utilities."
+    if category == "state":
+        return "Inspects or repairs project state metadata."
+    if category == "work-order":
+        return "Supports typed work-order execution and validation."
+    if category == "advanced/internal":
+        return "Advanced or internal helper; not a primary GUI action."
+    return f"Classified command: {qualified or leaf}"
+
+
+def build_command_taxonomy_report(project_root: Path) -> CommandTaxonomyReport:
+    commands = load_command_reference(project_root.resolve())
+    entries = tuple(classify_command(command) for command in commands)
+    findings: list[str] = []
+
+    if not entries:
+        findings.append("command reference contains no commands")
+
+    allowed = set(ALLOWED_COMMAND_CATEGORIES)
+    for entry in entries:
+        if not entry.qualified_name:
+            findings.append("command without qualified_name")
+        if entry.category not in allowed:
+            findings.append(f"{entry.qualified_name}: unsupported category {entry.category}")
+        if not entry.role:
+            findings.append(f"{entry.qualified_name}: missing role")
+        if entry.composition_level not in {"composite", "elementary", "elementary/internal"}:
+            findings.append(f"{entry.qualified_name}: unsupported composition level {entry.composition_level}")
+        if not 0 <= entry.recommendation_weight <= 100:
+            findings.append(f"{entry.qualified_name}: recommendation weight outside 0..100")
+        if entry.group == "root" and entry.category == "core" and entry.qualified_name.startswith("agentic-kit audit-"):
+            findings.append(f"{entry.qualified_name}: audit command classified as core")
+
+    return CommandTaxonomyReport(
+        command_count=len(commands),
+        entries=entries,
+        findings=tuple(findings),
+    )
+
+
+def render_command_taxonomy_report(report: CommandTaxonomyReport) -> str:
+    lines = [
+        "COMMAND_TAXONOMY_CHECK",
+        f"STATUS={report.status}",
+        f"COMMAND_COUNT={report.command_count}",
+        f"FINDING_COUNT={len(report.findings)}",
+    ]
+    by_category: dict[str, int] = {}
+    for entry in report.entries:
+        by_category[entry.category] = by_category.get(entry.category, 0) + 1
+    for category, count in sorted(by_category.items()):
+        lines.append(f"CATEGORY={category}|{count}")
+    by_level: dict[str, int] = {}
+    for entry in report.entries:
+        by_level[entry.composition_level] = by_level.get(entry.composition_level, 0) + 1
+    for level, count in sorted(by_level.items()):
+        lines.append(f"COMPOSITION_LEVEL={level}|{count}")
+    for entry in sorted(report.entries, key=lambda item: (-item.recommendation_weight, item.qualified_name))[:12]:
+        if entry.recommendation_weight >= 90:
+            lines.append(
+                f"PREFERRED={entry.qualified_name}|level={entry.composition_level}|weight={entry.recommendation_weight}"
+            )
+    for finding in report.findings:
+        lines.append(f"FINDING={finding}")
+    return "\n".join(lines) + "\n"