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

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

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

{assertion_cli-0.5.0 → 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.0
+Version: 0.5.2
 Summary: CLI for the Assertion API
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown

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

@@ -109,7 +109,11 @@ def _apply_marked_block(path: Path, body: str, repo_root: Path) -> None:
     if path.exists():
         current = path.read_text(encoding="utf-8")
         if pattern.search(current):
-            new_content = pattern.sub(marked_block, current)
+            # Replace via a callable so re.sub does NOT interpret backslash
+            # escapes (e.g. `\n`, `\g`) in the block — the activation template
+            # contains literal shell snippets like `printf '%s\n\n...'`, and a
+            # string replacement would mangle them, breaking init idempotency.
+            new_content = pattern.sub(lambda _match: marked_block, current)
         else:
             sep = (
                 ""
@@ -542,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.0 → assertion_cli-0.5.2}/pyproject.toml

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

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

@@ -9,6 +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 with `gh pr create` and include the session URL (from `asrt get-link`) in the body.
+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:
 
-Do not open a PR without a clean `asrt verify`.
+   ```
+   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 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 body omits the session marker.

{assertion_cli-0.5.0 → 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. 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,17 +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 (e.g., for inclusion in PR descriptions).
+`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 with `gh pr create`. Include the session URL (printed by verify/status; also `asrt get-link`) in the PR body so reviewers can see the verification record. |
+| **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. |
 
-**Do not open a PR without a clean `asrt verify` / `asrt verify-status`.** Do not end a session with a failed/dirty verify unless the verification service itself is unavailable.
+### Embed the hidden session marker in the PR (required)
+
+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.
+
+`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:
+
+```
+gh pr create --title "<title>" --body "$(cat <<EOF
+<one-paragraph summary of *why*, not *what*>
+
+$(asrt get-link)
+EOF
+)"
+```
+
+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>
+
+$(asrt get-link)
+EOF
+)"
+```
+
+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 body omits the session marker.** Do not end a session with a failed/dirty verify unless the verification service itself is unavailable.
 
 ---
 
@@ -161,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                                 # retrieve the last session URL
+asrt get-link                                 # hidden PR marker — embed in the PR body (required)
 ```
 
 ## Environment
@@ -180,5 +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, 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.0 → 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"