cleveragents-core/tools/controller/master/audit_comments.py

"""Audit-comment templates and the post-commit substitution helper.

Phase 0 deliverable (grooming plan): the ``close_issue`` and
``defer_issue`` callbacks post a Markdown audit comment to Forgejo
that ties the action back to a row in the ``grooming_decisions``
audit table by its ``decision_id``.

The ``decision_id`` is only known **after** the in-txn audit-row
insert commits, so the templates carry a literal sentinel
``<substituted-from-step-1>`` that ``render_comment_template``
replaces with the actual id. All OTHER placeholders in the
templates use ``str.format``-style ``{name}`` markers and are
filled by the caller BEFORE the template reaches the render helper.

The two kinds of placeholders coexist because they live in
different lifecycle stages:

- ``{name}`` markers: caller-supplied values (gate, reason
  category, canonical PR number, LLM confidence/reasoning, etc.)
  — known at the moment the caller assembles the comment.
- ``<substituted-from-step-1>``: the audit row's primary key —
  known only after the DB transaction commits.

See ``.drew/regressions-plan.md`` Phase 0, "Audit ID
substitution" and decision #25 for the design rationale.
"""

from __future__ import annotations

import re

_PLACEHOLDER_RE = re.compile(r"<substituted-from-step-\d+>")
_KNOWN_PLACEHOLDERS: frozenset[str] = frozenset({"<substituted-from-step-1>"})


def render_comment_template(template: str, *, decision_id: int) -> str:
    """Substitute the post-commit ``decision_id`` into a comment template.

    Replaces every occurrence of ``<substituted-from-step-1>`` with the
    string form of ``decision_id``. Raises ``ValueError`` if the
    template contains any ``<substituted-from-step-N>`` marker for
    an unknown ``N`` (whitelist check — guards against silently
    leaving an unsubstituted placeholder in the posted comment).

    Does NOT scan for generic ``<...>`` patterns in the template,
    because the comment body legitimately contains user-controlled
    angle brackets (e.g. an LLM's preserved-value summary referencing
    a Java type like ``Map<String, Object>``).

    The helper is also defensive about the substitution itself:
    after the ``replace`` it re-checks that no
    ``<substituted-from-step-1>`` text remains in the output. The
    only way that could fail is a future caller-bug where the
    sentinel appears inside data that was substituted in by an
    earlier ``str.format`` call, which is worth catching loudly.
    """
    found = set(_PLACEHOLDER_RE.findall(template))
    unknown = found - _KNOWN_PLACEHOLDERS
    if unknown:
        raise ValueError(
            "render_comment_template: template contains unknown placeholders "
            f"{sorted(unknown)}; only {sorted(_KNOWN_PLACEHOLDERS)} are "
            "supported. Either add the placeholder to "
            "_KNOWN_PLACEHOLDERS + a substitution branch, or remove it "
            "from the template."
        )
    rendered = template.replace("<substituted-from-step-1>", str(decision_id))
    if "<substituted-from-step-1>" in rendered:
        raise RuntimeError(
            "render_comment_template: substitution failed — "
            "'<substituted-from-step-1>' still present after replace. "
            "This indicates an upstream bug (the sentinel appeared in a "
            "caller-supplied value)."
        )
    return rendered


# ─── close-comment template ─────────────────────────────────────────────
#
# Caller-supplied {name} placeholders (filled via str.format):
#   gate                 — "Gate 1" / "Gate 2" / "Gate 3"
#   reason_category      — one of the abandon-reason categories
#                          (see .drew/regressions-plan.md "Abandon-reason
#                          categories — by gate")
#   explanation          — one-paragraph human-readable rationale
#   canonical_pr_line    — "Canonical (if duplicate): #42" OR "" (no line)
#   confidence_line      — "LLM confidence (when applicable): high" OR ""
#   reasoning_line       — "LLM reasoning (when applicable): ..." OR ""
#
# Render-helper-supplied placeholder (filled by render_comment_template):
#   <substituted-from-step-1> — the grooming_decisions.decision_id
#
# The optional ``*_line`` placeholders are pre-formatted by the caller
# so the template stays linear. Empty-string substitution leaves a
# blank line; callers should pass either a fully-formed line or an
# empty string.

CLOSE_COMMENT_TEMPLATE = """\
[CONTROLLER-CLOSE:{gate}:{reason_category}]

{explanation}

Decision:
- Gate: {gate}
- Reason category: {reason_category}
{canonical_pr_line}
{confidence_line}
{reasoning_line}

Audit ID: <substituted-from-step-1>

---
Automated by the CleverAgents controller pipeline.
Identity: HAL9000 (pipeline action)
"""


# ─── defer-comment template ─────────────────────────────────────────────
#
# Caller-supplied {name} placeholders:
#   gate, reason_category, canonical_pr_number, confidence, reasoning,
#   preserved_value_line — "Preserved value (when applicable): ..." OR ""
#   workflow_id          — the deferred workflow's id (used in clear-SQL)
#
# Render-helper-supplied: <substituted-from-step-1>

DEFER_COMMENT_TEMPLATE = """\
[CONTROLLER-DEFER:{gate}:{reason_category}]

This PR has been deferred for re-evaluation. The controller has stepped back
from processing it. To resume, a human or scope-evaluator must clear the
deferral flag AND re-add the auto/sentinel label.

Decision:
- Gate: {gate}
- Reason category: {reason_category}
- Canonical: #{canonical_pr_number}
- LLM confidence: {confidence}
- LLM reasoning: {reasoning}
{preserved_value_line}

To clear the deferral (SQL):
    UPDATE workflows SET deferred_reason=NULL,
                          deferred_at=NULL,
                          deferred_target_workflow_id=NULL
    WHERE workflow_id = {workflow_id};

    INSERT INTO controller_events
      (workflow_id, ts, event_type, payload, cause, forgejo_write_pending, replay_attempts)
    VALUES ({workflow_id}, datetime('now'), 'deferral_cleared',
            json_object('cleared_by', 'operator', 'reason', '<your reason>'),
            'operator', 0, 0);

Audit ID: <substituted-from-step-1>

---
Automated by the CleverAgents controller pipeline.
Identity: HAL9000 (pipeline action)
"""


__all__ = [
    "CLOSE_COMMENT_TEMPLATE",
    "DEFER_COMMENT_TEMPLATE",
    "render_comment_template",
]