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

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

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

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

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

{assertion_cli-0.5.1 → assertion_cli-0.5.3}/git.py

@@ -120,6 +120,7 @@ def get_uncommitted_diff(repo_root: Path, base_sha: str) -> str:
         ]
 
         parts = [p for p in [tracked, "\n".join(untracked_diffs)] if p]
-        return "\n".join(parts)
+        diff = "\n".join(parts)
+        return diff + "\n" if diff else diff
     except RuntimeError as exc:
         exit_with_error(f"Failed to collect git diff: {exc}")

{assertion_cli-0.5.1 → assertion_cli-0.5.3}/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.3}/pyproject.toml

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

assertion_cli-0.5.3/templates/ACTIVATION.md

@@ -0,0 +1,50 @@
+# Assertion verification
+
+This repo uses the Assertion CLI (`asrt`) to track user intent and verify your work. The full workflow lives in the `assertion-cli` skill:
+
+- **Claude Code** — [`.claude/skills/assertion-cli/SKILL.md`](.claude/skills/assertion-cli/SKILL.md)
+- **Codex / Cursor** — [`.agents/skills/assertion-cli/SKILL.md`](.agents/skills/assertion-cli/SKILL.md)
+
+Both files are byte-identical. Read whichever your agent loads (or either one directly). In brief, follow these three rules for every conversation:
+
+1. **Log every user message:** run `asrt prompt "<exact text>"` before anything else, on every turn — it's the verifier's record of intent.
+2. **Checkpoint at trajectory-feedback moments**, not every change. First checkpoint: `asrt stacks`, pick the stack that fits, then `asrt checkpoint --stack <id> "<summary>"`; later ones drop `--stack` and auto-continue. A feature build is a handful of checkpoints.
+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 that PR **must** carry the hidden Assertion session marker (see below).
+
+---
+
+## ⚠️ REQUIRED: every PR must embed the hidden session marker
+
+**This is the single most-missed step, and it is not optional.** A PR opened from an Assertion session that omits the marker cannot be linked back to its verification, so the work reads as unverified.
+
+The Assertion GitHub bot links a PR to its verification session by **branch name first**. When the branch name doesn't match the one you verified on (you renamed it, the head ref differs, etc.), the bot falls back to reading the marker. No marker → no fallback → no link.
+
+`asrt get-link` prints the marker as an HTML comment that GitHub hides from the rendered description but still delivers to the bot in the webhook payload:
+
+```
+<!-- assertion-session: https://app.tryassertion.com/sessions/<id> -->
+```
+
+**Open the PR with the marker embedded** — never paste the bare URL into the visible body; use the command so the format stays exact:
+
+```
+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 instead of opening a new one:
+
+```
+gh pr edit --body "$(printf '%s\n\n%s\n' '<existing summary>' "$(asrt get-link)")"
+```
+
+**Then confirm it landed.** The marker won't show in the rendered description — that's expected — so verify it's in the raw body:
+
+```
+gh pr view --json body --jq .body | grep -q 'assertion-session:' && echo "marker present" || echo "MARKER MISSING — fix before continuing"
+```
+
+---
+
+## Hard gates (do not bypass)
+- **No PR whose body omits the session marker.** If `asrt get-link` has nothing to return, you haven't verified yet — go back to rule 3.
+- **Confirm the marker after creating/editing the PR** with the `gh pr view` check above. Treat a missing marker as a blocking error, not a warning.

{assertion_cli-0.5.1 → assertion_cli-0.5.3}/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
@@ -16,6 +16,8 @@ Before any `asrt` call:
 - You are inside a git repository.
 - `asrt init` has been run in this repo. It records the current HEAD as the diff base that every checkpoint/verify diffs against, and installs the skill files you are reading right now. If `asrt checkpoint` or `asrt verify` errors with "No diff base recorded", run `asrt init` and retry.
 
+**Starting a fresh session:** when beginning a new session, delete the contents of `.assertion/` first. This clears the previous session's in-flight state (metadata, prompts log, link) so a new session starts clean and anchors to the stack you pick on the first checkpoint. Only the user should do this — it resets the session.
+
 Treat `.assertion/metadata.json`, `.assertion/prompts`, and `.assertion/base_sha` as internal state owned by the CLI. Do not create, edit, or delete those files manually — use `asrt prompt` to append to the prompts log.
 
 `asrt stacks` is read-only and lists every verification stack in the user's workspace, along with the repo each is configured for. Run it once per session before your first checkpoint so you can pick a stack ID; do not hardcode IDs from memory.
@@ -137,46 +139,59 @@ 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** 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:
 
-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.
+```
+<!-- assertion-session: https://app.tryassertion.com/sessions/<id> -->
+```
 
-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:
+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`.
+**Enforce it — don't assume it landed.** Immediately after creating or editing the PR, confirm the marker is in the raw body (it won't show in the rendered description — 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.
+```
+gh pr view --json body --jq .body | grep -q 'assertion-session:' \
+  && echo "marker present" \
+  || { echo "MARKER MISSING — re-run gh pr edit with \$(asrt get-link) before continuing"; exit 1; }
+```
+
+A missing marker is a **blocking error**, not a warning: do not consider the PR step complete, and do not move on, until this check prints `marker present`. Re-run `gh pr edit` with `$(asrt get-link)` and re-check until it passes.
+
+**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,13 +205,11 @@ 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
 
-- `ASSERTION_BASE_URL` — point the CLI at a non-default backend (default `http://localhost:8000`).
-
 ## Non-interactive / harness mode
 
 When running under a non-interactive harness (CI, benchmark runner, scripts):
@@ -209,6 +222,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.3}/tests/test_git.py

@@ -222,3 +222,36 @@ def test_get_uncommitted_diff_includes_local_only_commit_against_base(
     diff = get_uncommitted_diff(tmp_path, base_sha)
     assert "local.txt" in diff
     assert "+local change" in diff
+
+
+# --- trailing newline (diff must never be corrupt for git apply) ---
+
+
+def test_get_uncommitted_diff_ends_with_newline_when_not_empty(tmp_path: Path) -> None:
+    """Diff must end with \\n so git apply on the receiving end never chokes."""
+    _init_repo_with_commit(tmp_path)
+
+    # Tracked change
+    f = tmp_path / "file.txt"
+    f.write_text("content\n")
+    subprocess.run(
+        ["git", "add", "file.txt"], cwd=tmp_path, capture_output=True, check=True
+    )
+    subprocess.run(
+        ["git", "commit", "-m", "add file"],
+        cwd=tmp_path,
+        capture_output=True,
+        check=True,
+        env={**GIT_ENV, "HOME": str(tmp_path)},
+    )
+    f.write_text("modified\n")
+
+    diff = get_uncommitted_diff(tmp_path, "HEAD")
+    assert diff != ""
+    assert diff.endswith("\n"), f"tracked diff should end with newline, got: {diff[-10:]!r}"
+
+    # Untracked only
+    (tmp_path / "untracked.py").write_text("x = 1\n")
+    diff2 = get_uncommitted_diff(tmp_path, "HEAD")
+    assert diff2 != ""
+    assert diff2.endswith("\n"), f"untracked diff should end with newline, got: {diff2[-10:]!r}"

{assertion_cli-0.5.1 → assertion_cli-0.5.3}/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"

assertion_cli-0.5.1/templates/ACTIVATION.md

@@ -1,21 +0,0 @@
-# Assertion verification
-
-This repo uses the Assertion CLI (`asrt`) to track user intent and verify your work. The full workflow lives in the `assertion-cli` skill:
-
-- **Claude Code** — [`.claude/skills/assertion-cli/SKILL.md`](.claude/skills/assertion-cli/SKILL.md)
-- **Codex / Cursor** — [`.agents/skills/assertion-cli/SKILL.md`](.agents/skills/assertion-cli/SKILL.md)
-
-Both files are byte-identical. Read whichever your agent loads (or either one directly). In brief, follow these three rules for every conversation:
-
-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:
-
-   ```
-   SESSION_URL=$(asrt get-link)
-   gh pr create --title "<title>" --body "$(printf '%s\n\n**Assertion verification:** %s\n' '<one-paragraph why>' "$SESSION_URL")"
-   ```
-
-   If a PR already exists for the branch, add the line 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.