assertion-cli 0.5.1__tar.gz → 0.5.2__tar.gz

{assertion_cli-0.5.1 → assertion_cli-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertion-cli
-Version: 0.5.1
+Version: 0.5.2
 Summary: CLI for the Assertion API
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown

{assertion_cli-0.5.1 → assertion_cli-0.5.2}/assertion_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertion-cli
-Version: 0.5.1
+Version: 0.5.2
 Summary: CLI for the Assertion API
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown

{assertion_cli-0.5.1 → assertion_cli-0.5.2}/main.py

@@ -546,12 +546,33 @@ def verify_status(
         raise typer.Exit(code=1)
 
 
+PR_SESSION_MARKER_LABEL = "assertion-session:"
+
+
+def render_pr_session_marker(url: str) -> str:
+    """Render the hidden PR marker the Assertion GitHub bot parses.
+
+    An HTML comment: GitHub hides it from the rendered PR description but
+    delivers it verbatim in the webhook payload, so the bot can match a PR to
+    its verification session when the branch name doesn't line up. Keep the
+    format in sync with the parser in backend `api/v0/webhooks/router.py`.
+    """
+    return f"<!-- {PR_SESSION_MARKER_LABEL} {url} -->"
+
+
 @app.command("get-link")
 def get_link() -> None:
-    """Print the session link for the current verification session."""
+    """Print the hidden PR marker for the current verification session.
+
+    Emits `<!-- assertion-session: <url> -->`. Paste it into the PR body so the
+    Assertion GitHub bot can link the PR to this session when the branch name
+    doesn't match. GitHub does not render HTML comments, so it stays out of the
+    visible description. (The bare session URL is printed by `asrt verify` /
+    `asrt verify-status` and stored in `.assertion/link`.)
+    """
     ctx, metadata = load_existing_session(Path.cwd())
     url = load_link(ctx.assertion_dir)
-    typer.echo(url)
+    typer.echo(render_pr_session_marker(url))
 
 
 @app.command("decision")

{assertion_cli-0.5.1 → assertion_cli-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "assertion-cli"
-version = "0.5.1"
+version = "0.5.2"
 description = "CLI for the Assertion API"
 readme = "README.md"
 requires-python = ">=3.13"

{assertion_cli-0.5.1 → assertion_cli-0.5.2}/templates/ACTIVATION.md

@@ -9,13 +9,12 @@ Both files are byte-identical. Read whichever your agent loads (or either one di
 
 1. **Every user message:** call `asrt prompt "<exact text of the message>"` before doing any other work for that turn. This is the verifier's source of truth for what the user asked for and how their direction evolves. Apply to every user turn, not just the first.
 2. **Checkpoint at trajectory-feedback moments**, not on every small change. On the first checkpoint of a session, run `asrt stacks`, pick the stack that fits this repo and the work (use the stack's `repo`, `name`, `description`, plus folder/branch/README signals), then run `asrt checkpoint --stack <id> "<summary>"`. Subsequent checkpoints in the same session don't need `--stack` — `asrt checkpoint "<summary>"` auto-continues. A whole feature build is a handful of checkpoints, not one per file.
-3. **Verify at completion** with `asrt verify`. If feedback requires changes, iterate and re-verify — do **not** drop back into the checkpoint loop. Once verify is clean, open a PR and **put the Assertion session URL in the PR description** — this is required, not optional. Read the URL from `asrt get-link` (don't paste from memory) and include it on its own labeled line:
+3. **Verify at completion** with `asrt verify`. If feedback requires changes, iterate and re-verify — do **not** drop back into the checkpoint loop. Once verify is clean, open a PR and **embed the hidden Assertion session marker in its body** — this is required, not optional. The marker (`asrt get-link`) is an HTML comment GitHub hides from the rendered description but delivers to the Assertion GitHub bot, which uses it to link the PR to the verification when the branch name doesn't match:
 
    ```
-   SESSION_URL=$(asrt get-link)
-   gh pr create --title "<title>" --body "$(printf '%s\n\n**Assertion verification:** %s\n' '<one-paragraph why>' "$SESSION_URL")"
+   gh pr create --title "<title>" --body "$(printf '%s\n\n%s\n' '<one-paragraph why>' "$(asrt get-link)")"
    ```
 
-   If a PR already exists for the branch, add the line with `gh pr edit --body` instead of opening a new one.
+   If a PR already exists for the branch, add the marker with `gh pr edit --body` instead of opening a new one.
 
-Do not open a PR without a clean `asrt verify`, and do not open one whose description omits the session URL.
+Do not open a PR without a clean `asrt verify`, and do not open one whose body omits the session marker.

{assertion_cli-0.5.1 → assertion_cli-0.5.2}/templates/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assertion-cli
-description: Use this skill in non-Plan mode whenever working in a repo that uses the Assertion CLI (`asrt`). It enforces the three-rule workflow — log every user message with `asrt prompt`, checkpoint at trajectory-feedback moments (not on every change), and verify only at completion before opening a PR whose description includes the Assertion session URL. Applies to any coding agent reading this skill.
+description: Use this skill in non-Plan mode whenever working in a repo that uses the Assertion CLI (`asrt`). It enforces the three-rule workflow — log every user message with `asrt prompt`, checkpoint at trajectory-feedback moments (not on every change), and verify only at completion before opening a PR whose body embeds the hidden Assertion session marker. Applies to any coding agent reading this skill.
 ---
 
 # Assertion CLI
@@ -137,46 +137,51 @@ done
 
 `asrt verify-status` is a one-shot poll. It prints the current status, refreshes `.assertion/link`, and on terminal status writes screenshots under `.assertion/screenshots/<verification_id>/`. Exit code is `0` for `created` / `running` / `succeeded` and `1` for `failed`, so a polling loop can also branch on `$?`.
 
-`asrt get-link` prints the last session URL — the verification record reviewers open from the PR. Every PR you open from an Assertion session must carry this URL in its description (see *Put the session URL in the PR description* below).
+`asrt get-link` prints the hidden PR marker — an HTML comment carrying the session URL. Every PR you open from an Assertion session must embed it in the body so the Assertion GitHub bot can link the PR to the verification session — even when the branch name doesn't match (see *Embed the hidden session marker in the PR* below). The bare session URL, if you need it for something else, is printed by `asrt verify` / `asrt verify-status`.
 
 **After status reports terminal, branch on the outcome:**
 
 | Outcome | What you do next |
 |---|---|
-| **Clean** (succeeded, no required changes) | Open a PR and **put the session URL in the PR description** — mandatory, not optional. Use the exact command in *Put the session URL in the PR description* below. |
+| **Clean** (succeeded, no required changes) | Open a PR and **embed the hidden session marker in its body** — mandatory, not optional. Use the exact command in *Embed the hidden session marker in the PR* below. |
 | **Feedback or failed** (changes required) | Treat the feedback as authoritative. Apply the changes it calls for, then re-run `asrt verify` and poll `asrt verify-status` again. Repeat until clean. **Do not drop back into the checkpoint loop** — verify is the gate, not a checkpoint. |
 | **User sends a new message during iteration** | Log it with `asrt prompt` first (Rule 1 still applies). Address the new direction. Re-verify before opening the PR. |
 
-### Put the session URL in the PR description (required)
+### Embed the hidden session marker in the PR (required)
 
-Every PR opened from an Assertion session **must** include the verification session URL in its description. That URL is the reviewer's link to the verification record; a PR without it is incomplete. Do not bury it in a PR comment and do not omit it.
+Every PR opened from an Assertion session **must** carry the session marker in its body. The Assertion GitHub bot links a PR to its verification session by **branch name first**; when that doesn't match (you renamed the branch, or the PR's head ref differs from the one you verified on), it falls back to reading this marker. A PR without it can't be matched on the fallback path.
 
-Read the URL with `asrt get-link` and pass it to `gh pr create` so it lands in the body — don't paste a URL from memory:
+`asrt get-link` prints the marker as an HTML comment:
+
+```
+<!-- assertion-session: https://app.tryassertion.com/sessions/<id> -->
+```
+
+GitHub does not render HTML comments, so the marker stays out of the visible description but is delivered to the bot in the webhook payload. Do not paste the bare URL into the visible description — embed the marker via the command below so the format stays exact and machine-parseable:
 
 ```
-SESSION_URL=$(asrt get-link)
 gh pr create --title "<title>" --body "$(cat <<EOF
 <one-paragraph summary of *why*, not *what*>
 
-**Assertion verification:** $SESSION_URL
+$(asrt get-link)
 EOF
 )"
 ```
 
-If a PR already exists for this branch, edit its body instead of opening a new one:
+If a PR already exists for this branch, add the marker to its body instead of opening a new one:
 
 ```
 gh pr edit --body "$(cat <<EOF
 <existing summary>
 
-**Assertion verification:** $(asrt get-link)
+$(asrt get-link)
 EOF
 )"
 ```
 
-Keep the `Assertion verification:` label line verbatim so reviewers and tooling can find the link. After creating or editing the PR, confirm the URL is actually in the rendered description with `gh pr view --json body`.
+After creating or editing the PR, confirm the marker is in the raw body with `gh pr view --json body` — it won't show in the rendered description, and that's expected.
 
-**Do not open a PR without a clean `asrt verify` / `asrt verify-status`, and do not open one whose description omits the session URL.** Do not end a session with a failed/dirty verify unless the verification service itself is unavailable.
+**Do not open a PR without a clean `asrt verify` / `asrt verify-status`, and do not open one whose body omits the session marker.** Do not end a session with a failed/dirty verify unless the verification service itself is unavailable.
 
 ---
 
@@ -190,7 +195,7 @@ asrt checkpoint "..."                         # subsequent checkpoints — auto-
 asrt decision --yes|--no <ckpt-id>            # optional, on failed checkpoints only
 asrt verify                                   # submit verification (non-blocking)
 asrt verify-status                            # one-shot poll; loop with your own sleep
-asrt get-link                                 # last session URL — must go in the PR description
+asrt get-link                                 # hidden PR marker — embed in the PR body (required)
 ```
 
 ## Environment
@@ -209,6 +214,6 @@ When running under a non-interactive harness (CI, benchmark runner, scripts):
    - Re-run `asrt checkpoint "<what you changed>" --json` (auto-continues the existing session).
    - Bound retries: stop after 3 attempts on the same failure mode, or when the same `reasoning` is returned twice in a row.
 4. `asrt verify --json` submits and exits with a one-line JSON `{"session_id", "url", "status": "submitted"}`. Poll `asrt verify-status --json` on your own cadence — terminal output is `{"session_id", "url", "status", "message", "summary", "screenshot_count"}` with exit `1` on `failed`, `0` otherwise. Choose the poll interval to fit your harness timeouts; do not block a single shell call on verify.
-5. If the harness opens a PR, the `url` field (equivalently `asrt get-link`) is the session URL that **must** appear in the PR description — same requirement as interactive mode. Read it from the JSON rather than reconstructing it.
+5. If the harness opens a PR, embed the hidden session marker (`asrt get-link`) in the PR body — same requirement as interactive mode. The bot matches the PR to the session by branch first, then by this marker.
 
 Do not mix `--json` output with human-rendered output in the same run. Pick one mode and stick with it.

{assertion_cli-0.5.1 → assertion_cli-0.5.2}/tests/test_link.py

@@ -1,11 +1,19 @@
 from __future__ import annotations
 
+import re
 from pathlib import Path
 
 import pytest
 import typer
 
 from link import load_link, save_link
+from main import render_pr_session_marker
+
+# Must stay in sync with the bot-side parser in
+# backend/api/v0/webhooks/router.py (_SESSION_MARKER_RE).
+_BOT_MARKER_RE = re.compile(
+    r"assertion-session:\s*https?://\S+?/sessions/([A-Za-z0-9_-]+)"
+)
 
 
 def test_save_link_writes_file(tmp_path: Path) -> None:
@@ -29,3 +37,16 @@ def test_load_link_empty_file(tmp_path: Path) -> None:
     (tmp_path / "link").write_text("", encoding="utf-8")
     with pytest.raises(typer.Exit):
         load_link(tmp_path)
+
+
+def test_pr_session_marker_is_an_html_comment() -> None:
+    marker = render_pr_session_marker("https://app.tryassertion.com/sessions/sess-1")
+    assert marker.startswith("<!--") and marker.endswith("-->")
+
+
+def test_pr_session_marker_is_parseable_by_the_bot() -> None:
+    """The marker the CLI emits must yield the session id the bot extracts."""
+    marker = render_pr_session_marker("https://app.tryassertion.com/sessions/abc-123")
+    match = _BOT_MARKER_RE.search(marker)
+    assert match is not None
+    assert match.group(1) == "abc-123"