v0.52.0: GitHub Action sticky PR-comment output (gate · annotate · comment)

Add a 'comment' input/output to the Action: gate.py writes the findings summary
(Markdown) to the given path; the example workflow posts it as a sticky PR comment
via marocchino/sticky-pull-request-comment. Completes the CI UX alongside fail-on
(gate) and SARIF (annotations). +1 test.

Author: valani9

.github/action/gate.py

@@ -184,6 +184,13 @@ def main(env: dict[str, str] | None = None) -> int:
 
     summary = render_summary(report, findings, fail_on, failed, max_sev)
     _write_summary(summary)
+
+    comment_path = (env.get("VSTACK_COMMENT") or "").strip()
+    if comment_path:
+        with open(comment_path, "w", encoding="utf-8") as fh:
+            fh.write(summary)
+        _set_output("comment", comment_path)
+
     print(summary)
     return 1 if failed else 0
 

.github/action/test_gate.py

@@ -105,3 +105,36 @@ def test_sarif_from_report() -> None:
         results[0]["locations"][0]["physicalLocation"]["artifactLocation"]["uri"]
         == "traces/run.json"
     )
+
+
+def test_comment_file_written(tmp_path, monkeypatch) -> None:
+    # When VSTACK_COMMENT is set, main() writes the Markdown summary to it.
+    import json as _json
+
+    trace = tmp_path / "t.json"
+    trace.write_text(
+        _json.dumps(
+            {
+                "agent_id": "a",
+                "goal": "g",
+                "steps": [
+                    {"timestamp": "2026-01-01T00:00:00Z", "type": "observation", "content": "x"}
+                ],
+                "outcome": "o",
+                "success": False,
+            }
+        )
+    )
+    comment = tmp_path / "comment.md"
+    monkeypatch.chdir(tmp_path)
+    rc = gate.main(
+        {
+            "VSTACK_TRACE": str(trace),
+            "VSTACK_FAIL_ON": "high",
+            "VSTACK_CLIENT": "none",
+            "VSTACK_COMMENT": str(comment),
+        }
+    )
+    assert rc == 0
+    body = comment.read_text()
+    assert "vstack agent-quality gate" in body

CHANGELOG.md

@@ -6,6 +6,23 @@ project adheres to [Semantic Versioning](https://semver.org/) from
 `1.0.0` onward. During the `0.x` series, minor bumps may include
 breaking changes (see API stability promise in `vstack/__init__.py`).
 
+## [0.52.0] — 2026-06-23
+
+The Action's CI UX is now complete: gate · annotate · comment.
+
+### Added
+
+- **GitHub Action `comment` input + output** — set `comment: vstack-comment.md`
+  and the Action writes the findings summary (Markdown) to that path; the
+  example workflow posts it as a **sticky PR comment** via
+  `marocchino/sticky-pull-request-comment`, so findings land in the PR
+  conversation (not just the job summary). Complements the existing build
+  **gate** (`fail-on`) and code-scanning **annotations** (`sarif`). +1 test.
+
+### Compatibility
+
+- All tests pass. Opt-in; no breaking changes.
+
 ## [0.51.0] — 2026-06-23
 
 Bring-your-own-traces: import the logs you already have into a vstack trace.

README.md

@@ -542,7 +542,7 @@ vstack ships as a composite **GitHub Action** so you can shift agent-quality lef
     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
-It writes a findings table to the job summary and exposes `max-severity`, `findings-count`, `report`, and `sarif` outputs. With `client: none` it runs the deterministic analyzers only (no API key needed) — a free smoke gate. Set `sarif: vstack.sarif` to also emit a **SARIF 2.1.0** report and upload it with `github/codeql-action/upload-sarif` — findings then show up in the **Security tab and as PR annotations**. Full example: [examples/github-action/agent-quality-gate.yml](examples/github-action/agent-quality-gate.yml).
+It writes a findings table to the job summary and exposes `max-severity`, `findings-count`, `report`, `sarif`, and `comment` outputs. With `client: none` it runs the deterministic analyzers only (no API key needed) — a free smoke gate. The full CI UX: **gate** the build (`fail-on`), **annotate** the PR (`sarif: vstack.sarif` → `github/codeql-action/upload-sarif` → Security tab + inline annotations), and **comment** in the PR conversation (`comment: vstack-comment.md` → a sticky comment via `marocchino/sticky-pull-request-comment`). Full example: [examples/github-action/agent-quality-gate.yml](examples/github-action/agent-quality-gate.yml).
 
 Not on GitHub Actions? The same gating works from any shell — the core CLI is self-contained:
 

_packaging/vstack/__init__.py

@@ -73,7 +73,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.51.0"
+__version__ = "0.52.0"
 
 # The diagnose() function and PATTERNS registry are lazy-imported below
 # so that ``import vstack`` itself stays cheap. Pattern sub-packages

action.yml

@@ -42,6 +42,12 @@ inputs:
       github/codeql-action/upload-sarif to surface findings in code scanning).
     required: false
     default: ""
+  comment:
+    description: >-
+      If set to a path, write the findings summary (Markdown) there so you can
+      post it as a sticky PR comment (e.g. marocchino/sticky-pull-request-comment).
+    required: false
+    default: ""
   version:
     description: "valanistack version to install (e.g. '0.45.0'). Empty = latest."
     required: false
@@ -64,6 +70,9 @@ outputs:
   sarif:
     description: "Path to the written SARIF report (empty unless `sarif` input set)."
     value: ${{ steps.gate.outputs.sarif }}
+  comment:
+    description: "Path to the written Markdown comment (empty unless `comment` input set)."
+    value: ${{ steps.gate.outputs.comment }}
 
 runs:
   using: "composite"
@@ -106,4 +115,5 @@ runs:
         VSTACK_CLIENT: ${{ inputs.client }}
         VSTACK_SHAPE: ${{ inputs.shape }}
         VSTACK_SARIF: ${{ inputs.sarif }}
+        VSTACK_COMMENT: ${{ inputs.comment }}
       run: python "${{ github.action_path }}/.github/action/gate.py"

examples/github-action/agent-quality-gate.yml

@@ -35,13 +35,14 @@ jobs:
       # Full LLM-backed gate (needs a key in repo secrets):
       - name: vstack gate (LLM-backed)
         id: vstack
-        uses: valani9/vstack@v0.48.0
+        uses: valani9/vstack@v0.52.0
         with:
           trace: traces/latest.json
           client: anthropic
           mode: standard
           fail-on: high
-          sarif: vstack.sarif        # also emit SARIF for code scanning
+          sarif: vstack.sarif          # emit SARIF for code scanning
+          comment: vstack-comment.md   # write a Markdown findings summary
         env:
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 
@@ -52,3 +53,10 @@ jobs:
         uses: github/codeql-action/upload-sarif@v3
         with:
           sarif_file: ${{ steps.vstack.outputs.sarif }}
+
+      # Post (and keep updating) a sticky findings comment on the PR:
+      - name: Comment findings on PR
+        if: always() && github.event_name == 'pull_request' && steps.vstack.outputs.comment != ''
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          path: ${{ steps.vstack.outputs.comment }}

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "valanistack"
-version = "0.51.0"
+version = "0.52.0"
 description = "Organizational behavior, practiced on AI agents."
 readme = "README.md"
 requires-python = ">=3.11"