assertion-cli 0.5.11__tar.gz → 0.5.13__tar.gz

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/PKG-INFO

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

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/assertion_cli.egg-info/PKG-INFO

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

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/assertion_cli.egg-info/SOURCES.txt

@@ -23,7 +23,6 @@ tests/test_git.py
 tests/test_install.py
 tests/test_link.py
 tests/test_main.py
-tests/test_new.py
 tests/test_prompt.py
 tests/test_session.py
 tests/test_session_start.py

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/bundle.py

@@ -6,24 +6,21 @@ from models import MetadataPayload
 
 ASSERTION_DIR_NAME = ".assertion"
 DIFF_ARCHIVE_PATH = "git.diff"
-UNCOMMITTED_DIFF_ARCHIVE_PATH = "uncommitted.diff"
+REVIEW_DIFF_ARCHIVE_PATH = "review.diff"
 METADATA_ARCHIVE_PATH = f"{ASSERTION_DIR_NAME}/metadata.json"
 PROMPTS_ARCHIVE_PATH = f"{ASSERTION_DIR_NAME}/prompts"
 CHECKPOINT_ARCHIVE_PATH = f"{ASSERTION_DIR_NAME}/checkpoint"
 
 
 def _metadata_wire_json(metadata: MetadataPayload) -> str:
-    """Serialize metadata for the bundle, remapping `base_sha` → `head_sha`.
+    """Serialize metadata for the bundle.
 
-    The CLI stores the diff base as `base_sha` because that matches what the
-    field means from the CLI's perspective (the foundation the diff builds
-    on). The backend reads it as `head_sha` because after its `git checkout`
-    that SHA literally is the clone's HEAD. Same value, different name per
-    side; the remap lives here so neither side has to know about the other's
-    perspective.
+    `clone_sha` is the remote commit the backend sandbox checks out, so it is
+    emitted as `head_sha` on the wire. `base_sha` is the verification base
+    (where the user wants to start verifying from) and is emitted as-is.
     """
     payload = metadata.model_dump()
-    payload["head_sha"] = payload.pop("base_sha", None)
+    payload["head_sha"] = payload.pop("clone_sha", None)
     return json.dumps(payload, indent=2) + "\n"
 
 
@@ -31,7 +28,7 @@ def build_bundle(
     *,
     metadata: MetadataPayload,
     diff_text: str,
-    uncommitted_diff_text: str,
+    review_diff_text: str,
     prompts_text: str,
     checkpoint_text: str,
 ) -> bytes:
@@ -41,5 +38,5 @@ def build_bundle(
         zf.writestr(PROMPTS_ARCHIVE_PATH, prompts_text)
         zf.writestr(CHECKPOINT_ARCHIVE_PATH, checkpoint_text)
         zf.writestr(DIFF_ARCHIVE_PATH, diff_text)
-        zf.writestr(UNCOMMITTED_DIFF_ARCHIVE_PATH, uncommitted_diff_text)
+        zf.writestr(REVIEW_DIFF_ARCHIVE_PATH, review_diff_text)
     return buf.getvalue()

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/git.py

@@ -132,6 +132,55 @@ def get_merge_base(repo_root: Path, upstream: str) -> str:
         )
 
 
+def is_ancestor(repo_root: Path, maybe_ancestor: str, descendant: str) -> bool:
+    """Return True if *maybe_ancestor* is an ancestor of *descendant*."""
+    try:
+        run_git_command(
+            repo_root, ["merge-base", "--is-ancestor", maybe_ancestor, descendant]
+        )
+        return True
+    except RuntimeError:
+        return False
+
+
+def get_remote_ancestor(repo_root: Path, sha: str) -> str | None:
+    """Return the newest remote commit that is an ancestor of *sha*.
+
+    Uses local remote-tracking refs so this works offline. Returns ``None``
+    when no remote-tracking ref contains an ancestor of *sha*.
+    """
+    try:
+        merged = run_git_command(
+            repo_root,
+            ["branch", "-r", "--merged", sha, "--format=%(refname:short)"],
+        )
+    except RuntimeError:
+        return None
+
+    candidates = [r for r in merged.splitlines() if r]
+    if not candidates:
+        return None
+
+    newest_ref: str | None = None
+    newest_ts = -1
+    for ref in candidates:
+        try:
+            ts = int(run_git_command(repo_root, ["log", "-1", "--format=%ct", ref]))
+        except (RuntimeError, ValueError):
+            continue
+        if ts > newest_ts:
+            newest_ts = ts
+            newest_ref = ref
+
+    if newest_ref is None:
+        return None
+
+    try:
+        return run_git_command(repo_root, ["merge-base", sha, newest_ref])
+    except RuntimeError:
+        return None
+
+
 def get_head_branch(repo_root: Path) -> str | None:
     """Return the current branch name, or None if HEAD is detached."""
     try:

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/main.py

@@ -17,22 +17,22 @@ from git import (
     get_full_diff,
     get_head_branch,
     get_head_sha,
-    get_merge_base,
-    get_uncommitted_diff,
+    get_remote_ancestor,
     get_upstream_ref,
+    is_ancestor,
     run_git_command,
 )
 from link import load_link, save_link
 from models import CheckpointResponse, SessionStatus, render_stack_list
 from session import (
     ASSERTION_DIR_NAME,
-    BASE_SHA_FILE_NAME,
     METADATA_FILE_NAME,
     PROMPTS_FILE_NAME,
+    VERIFY_BASE_SHA_FILE_NAME,
     append_checkpoint_entry,
     continue_session,
     load_existing_session,
-    read_init_base_sha,
+    read_init_verify_base_sha,
     start_new_session,
     update_metadata_anchor,
 )
@@ -264,18 +264,24 @@ session_app = typer.Typer(help="Manage Assertion work sessions.")
 app.add_typer(session_app, name="session")
 
 
-def _resolve_diff_base(repo_root: Path) -> str:
-    """Compute the merge-base with the upstream tracking branch.
+def _resolve_verify_base(repo_root: Path, from_ref: str | None) -> str:
+    """Resolve the verification base SHA.
 
-    Fetches from origin first so the merge-base SHA is guaranteed to exist
-    on the remote when the backend checks it out — stale remote tracking
-    refs (from a force-pushed or rebased branch) would otherwise produce a
-    merge-base that's no longer reachable from any remote ref.
-
-    Falls back to HEAD when no upstream can be resolved (e.g. Codex cloud
-    sandboxes with no remote tracking refs) — the branch was cloned from the
-    remote so HEAD exists on the remote at session start time.
+    If *from_ref* is provided, resolve it and validate that it is an ancestor
+    of HEAD. Otherwise compute the merge-base with the upstream tracking branch,
+    falling back to HEAD when no upstream is available.
     """
+    if from_ref is not None:
+        try:
+            sha = run_git_command(repo_root, ["rev-parse", "--verify", from_ref])
+        except RuntimeError as exc:
+            exit_with_error(f"Invalid --from ref '{from_ref}': {exc}")
+        if not is_ancestor(repo_root, sha, "HEAD"):
+            exit_with_error(
+                f"--from ref {sha[:12]} is not an ancestor of HEAD."
+            )
+        return sha
+
     try:
         run_git_command(repo_root, ["fetch", "--no-tags", "origin"])
     except RuntimeError:
@@ -288,18 +294,61 @@ def _resolve_diff_base(repo_root: Path) -> str:
             err=True,
         )
         return get_head_sha(repo_root)
-    return get_merge_base(repo_root, upstream)
+    try:
+        return run_git_command(repo_root, ["merge-base", "HEAD", upstream])
+    except RuntimeError as exc:
+        exit_with_error(
+            f"Failed to compute merge-base between HEAD and {upstream}: {exc}"
+        )
+
+
+def _resolve_clone_anchor(repo_root: Path, verify_base: str) -> str:
+    """Return a remote commit the sandbox can check out.
+
+    If *verify_base* itself is reachable from a remote ref, use it. Otherwise
+    find the newest remote ancestor of *verify_base*. If no remote is reachable
+    at all, fall back to HEAD (the branch was cloned from the remote).
+    """
+    ancestor = get_remote_ancestor(repo_root, verify_base)
+    if ancestor is not None:
+        return ancestor
+
+    typer.echo(
+        "Warning: no remote reachable, falling back to HEAD for clone anchor.",
+        err=True,
+    )
+    return get_head_sha(repo_root)
+
+
+def _reset_assertion_dir(assertion_dir: Path) -> int:
+    """Remove all local Assertion state, keeping committed seed hooks trackable."""
+    removed = 0
+    if not assertion_dir.exists():
+        return removed
+    for child in assertion_dir.iterdir():
+        if child.name == "seed.py":
+            continue
+        if child.is_dir():
+            shutil.rmtree(child)
+        else:
+            child.unlink()
+        removed += 1
+    return removed
 
 
 @session_app.command("start")
-def session_start() -> None:
-    """Record the merge-base with the upstream tracking branch as the diff base.
+def session_start(
+    from_ref: str | None = typer.Option(
+        None,
+        "--from",
+        help="Verification base ref (commit/branch/tag). Defaults to merge-base with upstream.",
+    ),
+) -> None:
+    """Start a fresh Assertion session and record the verification base.
 
-    Unlike the old HEAD-based approach, the merge-base always exists on the
-    remote so the backend can check it out. When no upstream tracking branch
-    can be resolved (e.g. Codex cloud sandboxes), falls back to HEAD — the
-    branch was cloned from the remote so HEAD exists on the remote at session
-    start time.
+    Resets `.assertion/` (except `.assertion/seed.py`) so each session starts
+    clean. When no upstream tracking branch can be resolved, falls back to
+    HEAD as the verification base.
 
     `session start` does not write skill files — that is `asrt install`, the
     one-time onboarding step. It also never touches user content in `CLAUDE.md` /
@@ -309,14 +358,20 @@ def session_start() -> None:
     repo_root = find_git_root(Path.cwd())
     _ensure_gitignore_limits_assertion_state(repo_root)
 
-    base_sha = _resolve_diff_base(repo_root)
+    verify_base = _resolve_verify_base(repo_root, from_ref)
     assertion_dir = repo_root / ASSERTION_DIR_NAME
     assertion_dir.mkdir(exist_ok=True)
-    base_sha_path = assertion_dir / BASE_SHA_FILE_NAME
-    base_sha_path.write_text(base_sha + "\n", encoding="utf-8")
+    removed = _reset_assertion_dir(assertion_dir)
+
+    verify_base_path = assertion_dir / VERIFY_BASE_SHA_FILE_NAME
+    verify_base_path.write_text(verify_base + "\n", encoding="utf-8")
     typer.echo(
-        f"Recorded diff base {base_sha[:12]} → {base_sha_path.relative_to(repo_root)}"
+        f"Recorded verification base {verify_base[:12]} → {verify_base_path.relative_to(repo_root)}"
     )
+    if removed:
+        typer.echo(
+            f"Cleared {removed} prior .assertion entr{'y' if removed == 1 else 'ies'}."
+        )
 
     typer.echo("")
     typer.echo("The coding agent will now follow the Assertion workflow:")
@@ -325,31 +380,6 @@ def session_start() -> None:
     typer.echo("  - asrt verify at completion, then PR")
 
 
-@app.command("new")
-def new() -> None:
-    """Reset local Assertion run state and record the merge-base as the diff base."""
-    repo_root = find_git_root(Path.cwd())
-    base_sha = _resolve_diff_base(repo_root)
-    assertion_dir = repo_root / ASSERTION_DIR_NAME
-    assertion_dir.mkdir(exist_ok=True)
-
-    removed = 0
-    for child in assertion_dir.iterdir():
-        if child.is_dir():
-            shutil.rmtree(child)
-        else:
-            child.unlink()
-        removed += 1
-
-    base_sha_path = assertion_dir / BASE_SHA_FILE_NAME
-    base_sha_path.write_text(base_sha + "\n", encoding="utf-8")
-
-    typer.echo(f"Cleared {removed} .assertion entr{'y' if removed == 1 else 'ies'}.")
-    typer.echo(
-        f"Recorded diff base {base_sha[:12]} → {base_sha_path.relative_to(repo_root)}"
-    )
-
-
 @app.command("prompt")
 def prompt_cmd(
     text: str = typer.Argument(..., help="User prompt text to record."),
@@ -434,18 +464,23 @@ def checkpoint(
     assert stack_id is not None
 
     append_checkpoint_entry(ctx.checkpoint_path, message)
-    base_sha = read_init_base_sha(ctx.assertion_dir)
+    verify_base = read_init_verify_base_sha(ctx.assertion_dir)
+    clone_anchor = _resolve_clone_anchor(ctx.repo_root, verify_base)
     head_branch = get_head_branch(ctx.repo_root)
-    diff_text = get_full_diff(ctx.repo_root, base_sha)
-    uncommitted_diff_text = get_uncommitted_diff(ctx.repo_root)
+    diff_text = get_full_diff(ctx.repo_root, clone_anchor)
+    review_diff_text = get_full_diff(ctx.repo_root, verify_base)
     metadata = update_metadata_anchor(
-        ctx.metadata_path, metadata, base_sha, head_branch=head_branch
+        ctx.metadata_path,
+        metadata,
+        verify_base,
+        clone_sha=clone_anchor,
+        head_branch=head_branch,
     )
 
     bundle_bytes = build_bundle(
         metadata=metadata,
         diff_text=diff_text,
-        uncommitted_diff_text=uncommitted_diff_text,
+        review_diff_text=review_diff_text,
         prompts_text=ctx.prompts_path.read_text(encoding="utf-8"),
         checkpoint_text=message,
     )
@@ -536,18 +571,23 @@ def verify(
     ctx, metadata = load_existing_session(Path.cwd())
     stack_id = metadata.stack_id
     assert stack_id is not None
-    base_sha = read_init_base_sha(ctx.assertion_dir)
+    verify_base = read_init_verify_base_sha(ctx.assertion_dir)
+    clone_anchor = _resolve_clone_anchor(ctx.repo_root, verify_base)
     head_branch = get_head_branch(ctx.repo_root)
-    diff_text = get_full_diff(ctx.repo_root, base_sha)
-    uncommitted_diff_text = get_uncommitted_diff(ctx.repo_root)
+    diff_text = get_full_diff(ctx.repo_root, clone_anchor)
+    review_diff_text = get_full_diff(ctx.repo_root, verify_base)
     metadata = update_metadata_anchor(
-        ctx.metadata_path, metadata, base_sha, head_branch=head_branch
+        ctx.metadata_path,
+        metadata,
+        verify_base,
+        clone_sha=clone_anchor,
+        head_branch=head_branch,
     )
 
     bundle_bytes = build_bundle(
         metadata=metadata,
         diff_text=diff_text,
-        uncommitted_diff_text=uncommitted_diff_text,
+        review_diff_text=review_diff_text,
         prompts_text=ctx.prompts_path.read_text(encoding="utf-8"),
         checkpoint_text=ctx.checkpoint_path.read_text(encoding="utf-8"),
     )

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/models.py

@@ -64,13 +64,12 @@ class ErrorResponse(BaseModel):
 class MetadataPayload(BaseModel):
     """Local on-disk schema for `.assertion/metadata.json`.
 
-    `base_sha` is the diff base (the commit `asrt session start` recorded; the commit
-    the backend checks out before applying the diff). In the bundle sent to
-    the backend it is remapped to `head_sha` for wire compatibility — from
-    the backend's perspective, after `git checkout <sha>`, that SHA IS its
-    HEAD, so the name reads correctly on the consumer side. Locally we keep
-    `base_sha` because it matches what the CLI stores (`.assertion/base_sha`)
-    and what the value represents from the CLI's perspective.
+    `base_sha` is the verification base (the commit the user wants to start
+    verifying from). `clone_sha` is the commit the backend sandbox checks out
+    before applying the diff; it is always a remote commit (or `HEAD` as a
+    fallback when no remote is reachable). The bundle wire format maps
+    `clone_sha` to `head_sha` because from the backend's perspective that
+    SHA is the clone's HEAD.
     """
 
     model_config = ConfigDict(extra="allow")
@@ -78,6 +77,7 @@ class MetadataPayload(BaseModel):
     session_id: str
     stack_id: str | None = None
     base_sha: str | None = None
+    clone_sha: str | None = None
     head_branch: str | None = None
 
 

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/pyproject.toml

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

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/session.py

@@ -13,28 +13,26 @@ ASSERTION_DIR_NAME = ".assertion"
 PROMPTS_FILE_NAME = "prompts"
 CHECKPOINT_FILE_NAME = "checkpoint"
 METADATA_FILE_NAME = "metadata.json"
-BASE_SHA_FILE_NAME = "base_sha"
+VERIFY_BASE_SHA_FILE_NAME = "verify_base_sha"
 
 
-def read_init_base_sha(assertion_dir: Path) -> str:
-    """Return the diff base SHA recorded by `asrt session start`.
+def read_init_verify_base_sha(assertion_dir: Path) -> str:
+    """Return the verification base SHA recorded by `asrt session start`.
 
-    The base SHA is the merge-base with the upstream tracking branch — always
-    fetchable from the remote. Every checkpoint/verify reads this value; it
-    never changes within a session.
+    The verify base is the commit the user wants to start verifying from.
+    Every checkpoint/verify reads this value; it never changes within a session.
     """
-    path = assertion_dir / BASE_SHA_FILE_NAME
+    path = assertion_dir / VERIFY_BASE_SHA_FILE_NAME
     if not path.exists():
         exit_with_error(
-            "No diff base recorded for this repo. Run `asrt session start` "
-            "first — it captures the merge-base SHA that checkpoint/verify "
-            "diff against."
+            "No verification base recorded for this repo. Run `asrt session start` "
+            "first — it captures the commit that checkpoint/verify diff against."
         )
     content = path.read_text(encoding="utf-8").strip()
     if not content:
         exit_with_error(
             f"{path.name} is empty. Re-run `asrt session start` to record the "
-            "diff base."
+            "verification base."
         )
     return content
 
@@ -43,7 +41,7 @@ def _require_repo_ready(start_path: Path) -> Path:
     repo_root = find_git_root(start_path)
     # Fail fast if `asrt session start` hasn't run — checkpoint/verify need the
     # base SHA it records before doing any work or making any network calls.
-    read_init_base_sha(repo_root / ASSERTION_DIR_NAME)
+    read_init_verify_base_sha(repo_root / ASSERTION_DIR_NAME)
     return repo_root
 
 
@@ -191,16 +189,19 @@ def update_metadata_anchor(
     metadata_path: Path,
     metadata: MetadataPayload,
     base_sha: str,
+    clone_sha: str | None = None,
     head_branch: str | None = None,
 ) -> MetadataPayload:
-    """Refresh the per-session git anchor: diff base + branch name.
+    """Refresh the per-session git anchor: diff base + clone anchor + branch name.
 
-    `base_sha` is the diff base (recorded by `asrt session start`, same value on
-    every call within a session). `head_branch` is the current local branch — may
-    legitimately change within a session if the user renames or switches.
+    `base_sha` is the verification base (recorded by `asrt session start`, same
+    value on every call within a session). `clone_sha` is the remote commit the
+    backend checks out, recomputed per checkpoint/verify. `head_branch` is the
+    current local branch — may legitimately change within a session.
     """
-    updated = metadata.model_copy(
-        update={"base_sha": base_sha, "head_branch": head_branch}
-    )
+    update: dict[str, object] = {"base_sha": base_sha, "head_branch": head_branch}
+    if clone_sha is not None:
+        update["clone_sha"] = clone_sha
+    updated = metadata.model_copy(update=update)
     metadata_path.write_text(updated.model_dump_json(indent=2) + "\n", encoding="utf-8")
     return updated

assertion_cli-0.5.13/templates/AGENTS.md

@@ -0,0 +1,26 @@
+# 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. Apply to every user turn, not just the first.
+2. **Checkpoint at trajectory-feedback moments** with `asrt checkpoint` — a handful across a feature build, not one per file.
+3. **Verify, then PR with the session marker.** At completion, run `asrt verify` and poll `asrt verify-status` until clean. Then open the PR and embed the hidden session marker — `$(asrt get-link)`, an HTML comment — in its body.
+
+**The session marker is mandatory, not optional.** It's an HTML comment carrying the session URL — `asrt get-link` prints exactly this form:
+
+```
+<!-- assertion-session: https://app.tryassertion.com/sessions/<id> -->
+```
+
+Every PR opened from an Assertion session **must** carry it: the Assertion GitHub bot links the PR to the verification session by branch name first, and falls back to this marker when the branch doesn't match — without it, that PR can't be linked. So:
+
+- Put `$(asrt get-link)` in the PR body via `gh pr create`/`gh pr edit` — never paste the bare URL into the visible description.
+- After creating or editing the PR, **confirm the marker actually landed in the raw body** (`gh pr view --json body --jq .body | grep -q 'assertion-session:'`). It won't show in the rendered description — that's expected.
+- A missing marker is a **blocking error, not a warning**: do not consider the task done, and do not open a PR at all, until the marker is verified present. Re-run `gh pr edit` with `$(asrt get-link)` and re-check until it passes.
+
+See the skill file for the full rules, edge cases, and the exact PR command (section: *Embed the hidden session marker in the PR*).

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/templates/SKILL.md

@@ -15,20 +15,14 @@ Before any `asrt` call:
 
 - You are inside a git repository.
 - `asrt install` has been run once in this repo. It installs the skill files you are reading right now (plus the `AGENTS.md` / `CLAUDE.md` pointer and `.gitignore` rules). This is an onboarding step, not a per-run one.
-- `asrt session start` has been run for this work session. It records the merge-base with the upstream tracking branch (falling back to HEAD when no upstream is available) as the diff base that every checkpoint/verify diffs against. If `asrt checkpoint` or `asrt verify` errors with "No diff base recorded", run `asrt session start` and retry.
+- `asrt session start` has been run for this work session. It resets `.assertion/` (except `.assertion/seed.py`) and records the verification base — the merge-base with the upstream tracking branch by default, or an explicit `--from <ref>`. If `asrt checkpoint` or `asrt verify` errors with "No verification base recorded", run `asrt session start` and retry.
 
 **First command sequence for a new work session:**
 
-1. Before any `asrt` call, check whether this repo may have previous Assertion state in `.assertion/`.
-2. If previous Assertion state exists, ask the user: "Do you want to clean up the previous Assertion session and start fresh?"
-3. When the harness supports structured prompts or selectable options, present the question with selectable `Yes` and `No` options. Do not ask the user to type `yes` or `no` unless selectable options are unavailable.
-4. If the user answers yes, run `asrt new` before any other `asrt` command.
-5. If the user answers no, continue with the existing session state.
-6. After the reset decision is resolved, immediately log the active user prompt with `asrt prompt`. Treat the cleanup confirmation itself as a control response, not user intent to record, when it only answers this reset question.
+1. Run `asrt session start` to start fresh. This clears previous in-flight Assertion state (metadata, prompts log, link, verification status, screenshots) and records the current verification base.
+2. Immediately log the active user prompt with `asrt prompt`.
 
-This check is the only allowed exception to Rule 1's "first thing" requirement: resolve it before the first `asrt prompt` call, because `asrt new` clears the prompts log. `asrt new` clears the previous session's in-flight state (metadata, prompts log, link, verification status, screenshots) and records the current `HEAD` as the new diff base, so a new session starts clean on the current branch and anchors to the stack you pick on the first checkpoint. Do not run `asrt new` without explicit user consent — 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 and `asrt new` to reset for a fresh session.
+Treat `.assertion/metadata.json`, `.assertion/prompts`, and `.assertion/verify_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 and `asrt session start` to reset for a fresh session.
 
 `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.
 
@@ -42,7 +36,7 @@ Treat `.assertion/metadata.json`, `.assertion/prompts`, and `.assertion/base_sha
 asrt prompt "<exact text of the user's message>"
 ```
 
-Exception: on the first user turn of a new work session, perform the Preflight fresh-session check first. If the user approves a reset, run `asrt new` before `asrt prompt`; otherwise skip the reset. Once that decision is resolved, immediately run `asrt prompt` for the active user message so the new/current session records the user's intent. If the only separate user message during preflight is a plain reset confirmation, do not record that confirmation as its own prompt.
+Exception: on the first user turn of a new work session, perform the Preflight fresh-session check first by running `asrt session start`, then immediately run `asrt prompt` for the active user message so the new/current session records the user's intent.
 
 This applies to **every user turn**, not just the first. It applies even when the message is a one-word direction change ("nope"), a clarification ("use Postgres, not SQLite"), or a follow-up after verify ("also add dark mode").
 
@@ -117,9 +111,9 @@ When you pass `--stack`, briefly state which stack you chose and why ("Picked st
 | CLI error starts with | What it means | What to do |
 |---|---|---|
 | `No session exists yet and no --stack given.` | First checkpoint of a fresh `.assertion/`, but you didn't pick a stack. | Run `asrt stacks`, pick one using the signals above, pass `--stack <id>`. |
-| `This session is already anchored to a stack.` | You passed `--stack` after a session was already created. The CLI locks the stack at session creation. | Drop the `--stack` flag and re-run `asrt checkpoint "<message>"`, or ask the user to run `asrt new` if this should be a fresh session. |
+| `This session is already anchored to a stack.` | You passed `--stack` after a session was already created. The CLI locks the stack at session creation. | Drop the `--stack` flag and re-run `asrt checkpoint "<message>"`, or run `asrt session start` if this should be a fresh session. |
 | `ERROR: Unknown stack '<id>'.` | The `--stack` you passed is not in the workspace. | Re-run `asrt stacks` (the list may have changed) and pass a valid id. |
-| `No diff base recorded for this repo.` | `asrt session start` wasn't run. | Run `asrt session start` and retry. |
+| `No verification base recorded for this repo.` | `asrt session start` wasn't run. | Run `asrt session start` and retry. |
 | `ERROR: No active session to continue.` | You passed `--continue` but there is no session. | Drop `--continue` and pass `--stack <id>` to start one. |
 
 ---
@@ -205,7 +199,7 @@ A missing marker is a **blocking error**, not a warning: do not consider the PR
 
 **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.
 
-**After the PR marker is confirmed:** ask the user whether they want to clean up the completed Assertion session and start fresh for the next session. If the user says yes, run `asrt new`. If the user says no, leave the existing `.assertion/` state intact.
+**After the PR marker is confirmed:** ask the user whether they want to clean up the completed Assertion session and start fresh for the next session. If the user says yes, run `asrt session start`. If the user says no, leave the existing `.assertion/` state intact.
 
 ---
 
@@ -213,7 +207,7 @@ A missing marker is a **blocking error**, not a warning: do not consider the PR
 
 ```
 asrt prompt "<message>"                       # every user turn, before anything else
-asrt new                                      # reset local run state only after user consent
+asrt session start [--from <ref>]             # start fresh; optional explicit verification base
 asrt stacks                                   # list every stack — read once before first checkpoint
 asrt checkpoint --stack <id> "..."            # first checkpoint of a session
 asrt checkpoint "..."                         # subsequent checkpoints — auto-continues
@@ -237,6 +231,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.
+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 name 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.11 → assertion_cli-0.5.13}/tests/test_bundle.py

@@ -10,12 +10,15 @@ from models import MetadataPayload
 
 def test_build_bundle_writes_session_metadata() -> None:
     metadata = MetadataPayload(
-        session_id="session-1", stack_id="stack-1", base_sha="abc123"
+        session_id="session-1",
+        stack_id="stack-1",
+        base_sha="base123",
+        clone_sha="clone456",
     )
     bundle_bytes = build_bundle(
         metadata=metadata,
         diff_text="diff --git a/file b/file",
-        uncommitted_diff_text="diff --git a/file b/file",
+        review_diff_text="review diff",
         prompts_text='{"ts": "2026-05-28T14:32:01Z", "text": "Do the thing"}\n',
         checkpoint_text="Checkpoint text",
     )
@@ -24,11 +27,9 @@ def test_build_bundle_writes_session_metadata() -> None:
         meta_json = json.loads(zf.read(".assertion/metadata.json").decode("utf-8"))
         assert meta_json["session_id"] == "session-1"
         assert meta_json["stack_id"] == "stack-1"
-        # Wire-format remap: local `base_sha` ships as `head_sha`. The backend
-        # has not been migrated, so the bundle key must remain `head_sha` and
-        # `base_sha` must not leak through.
-        assert meta_json["head_sha"] == "abc123"
-        assert "base_sha" not in meta_json
+        # clone_sha is the remote checkout anchor, so it ships as head_sha.
+        assert meta_json["head_sha"] == "clone456"
+        assert meta_json["base_sha"] == "base123"
 
         prompts_raw = zf.read(".assertion/prompts").decode("utf-8")
         assert '"text": "Do the thing"' in prompts_raw
@@ -37,5 +38,5 @@ def test_build_bundle_writes_session_metadata() -> None:
         git_diff = zf.read("git.diff").decode("utf-8")
         assert "diff --git a/file b/file" in git_diff
 
-        uncommitted_diff = zf.read("uncommitted.diff").decode("utf-8")
-        assert "diff --git a/file b/file" in uncommitted_diff
+        review_diff = zf.read("review.diff").decode("utf-8")
+        assert "review diff" in review_diff

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/tests/test_git.py

@@ -2,15 +2,17 @@ import subprocess
 from pathlib import Path
 
 import pytest
-from click.exceptions import Exit as ClickExit
+import typer
 
 from git import (
     find_git_root,
     get_full_diff,
     get_head_sha,
     get_merge_base,
+    get_remote_ancestor,
     get_uncommitted_diff,
     get_upstream_ref,
+    is_ancestor,
     run_git_command,
 )
 
@@ -41,7 +43,7 @@ def test_find_git_root_in_repo(tmp_path: Path) -> None:
 
 
 def test_find_git_root_outside_repo(tmp_path: Path) -> None:
-    with pytest.raises(ClickExit):
+    with pytest.raises(typer.Exit):
         find_git_root(tmp_path)
 
 
@@ -656,3 +658,134 @@ def test_get_uncommitted_diff_preserves_trailing_blank_context_lines(
         check=False,
     )
     assert apply_check.returncode == 0, apply_check.stderr
+
+
+# --- is_ancestor ---
+
+
+def test_is_ancestor_true_for_parent(tmp_path: Path) -> None:
+    subprocess.run(["git", "init"], cwd=tmp_path, capture_output=True, check=True)
+    subprocess.run(
+        ["git", "commit", "--allow-empty", "-m", "first"],
+        cwd=tmp_path,
+        capture_output=True,
+        check=True,
+        env={**GIT_ENV, "HOME": str(tmp_path)},
+    )
+    parent = run_git_command(tmp_path, ["rev-parse", "HEAD"])
+    subprocess.run(
+        ["git", "commit", "--allow-empty", "-m", "second"],
+        cwd=tmp_path,
+        capture_output=True,
+        check=True,
+        env={**GIT_ENV, "HOME": str(tmp_path)},
+    )
+    head = run_git_command(tmp_path, ["rev-parse", "HEAD"])
+
+    assert is_ancestor(tmp_path, parent, head) is True
+
+
+def test_is_ancestor_false_for_sibling(tmp_path: Path) -> None:
+    subprocess.run(["git", "init"], cwd=tmp_path, capture_output=True, check=True)
+    subprocess.run(
+        ["git", "commit", "--allow-empty", "-m", "first"],
+        cwd=tmp_path,
+        capture_output=True,
+        check=True,
+        env={**GIT_ENV, "HOME": str(tmp_path)},
+    )
+    parent = run_git_command(tmp_path, ["rev-parse", "HEAD"])
+    subprocess.run(
+        ["git", "commit", "--allow-empty", "-m", "second"],
+        cwd=tmp_path,
+        capture_output=True,
+        check=True,
+        env={**GIT_ENV, "HOME": str(tmp_path)},
+    )
+    sibling = subprocess.run(
+        ["git", "commit-tree", "HEAD^{tree}", "-p", parent, "-m", "sibling"],
+        cwd=tmp_path,
+        capture_output=True,
+        text=True,
+        check=True,
+        env={**GIT_ENV, "HOME": str(tmp_path)},
+    ).stdout.strip()
+
+    assert is_ancestor(tmp_path, sibling, "HEAD") is False
+
+
+# --- get_remote_ancestor ---
+
+
+def test_get_remote_ancestor_returns_sha_when_on_remote(tmp_path: Path) -> None:
+    subprocess.run(["git", "init"], cwd=tmp_path, capture_output=True, check=True)
+    subprocess.run(
+        ["git", "commit", "--allow-empty", "-m", "first"],
+        cwd=tmp_path,
+        capture_output=True,
+        check=True,
+        env={**GIT_ENV, "HOME": str(tmp_path)},
+    )
+    sha = run_git_command(tmp_path, ["rev-parse", "HEAD"])
+    subprocess.run(
+        ["git", "remote", "add", "origin", "http://example.com/repo.git"],
+        cwd=tmp_path,
+        capture_output=True,
+        check=True,
+    )
+    subprocess.run(
+        ["git", "update-ref", "refs/remotes/origin/main", sha],
+        cwd=tmp_path,
+        capture_output=True,
+        check=True,
+    )
+
+    assert get_remote_ancestor(tmp_path, sha) == sha
+
+
+def test_get_remote_ancestor_returns_nearest_remote_ancestor(tmp_path: Path) -> None:
+    subprocess.run(["git", "init"], cwd=tmp_path, capture_output=True, check=True)
+    subprocess.run(
+        ["git", "commit", "--allow-empty", "-m", "remote"],
+        cwd=tmp_path,
+        capture_output=True,
+        check=True,
+        env={**GIT_ENV, "HOME": str(tmp_path)},
+    )
+    remote_sha = run_git_command(tmp_path, ["rev-parse", "HEAD"])
+    subprocess.run(
+        ["git", "commit", "--allow-empty", "-m", "local"],
+        cwd=tmp_path,
+        capture_output=True,
+        check=True,
+        env={**GIT_ENV, "HOME": str(tmp_path)},
+    )
+    local_sha = run_git_command(tmp_path, ["rev-parse", "HEAD"])
+    subprocess.run(
+        ["git", "remote", "add", "origin", "http://example.com/repo.git"],
+        cwd=tmp_path,
+        capture_output=True,
+        check=True,
+    )
+    subprocess.run(
+        ["git", "update-ref", "refs/remotes/origin/main", remote_sha],
+        cwd=tmp_path,
+        capture_output=True,
+        check=True,
+    )
+
+    assert get_remote_ancestor(tmp_path, local_sha) == remote_sha
+
+
+def test_get_remote_ancestor_returns_none_without_remote(tmp_path: Path) -> None:
+    subprocess.run(["git", "init"], cwd=tmp_path, capture_output=True, check=True)
+    subprocess.run(
+        ["git", "commit", "--allow-empty", "-m", "first"],
+        cwd=tmp_path,
+        capture_output=True,
+        check=True,
+        env={**GIT_ENV, "HOME": str(tmp_path)},
+    )
+    sha = run_git_command(tmp_path, ["rev-parse", "HEAD"])
+
+    assert get_remote_ancestor(tmp_path, sha) is None

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/tests/test_install.py

@@ -131,11 +131,8 @@ def test_install_records_skill_cleanup_guidance(tmp_path: Path, monkeypatch) ->
 
     skill = (tmp_path / ".agents" / "skills" / "assertion-cli" / "SKILL.md").read_text()
     assert "First command sequence for a new work session" in skill
-    assert (
-        'ask the user: "Do you want to clean up the previous Assertion session '
-        'and start fresh?"'
-    ) in skill
-    assert "Do not run `asrt new` without explicit user consent" in skill
+    assert "`asrt session start`" in skill
+    assert "`asrt new`" not in skill
 
 
 def test_install_requires_git_repo(tmp_path: Path, monkeypatch) -> None:

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/tests/test_session.py

@@ -26,9 +26,10 @@ def test_update_metadata_anchor_preserves_session_id(tmp_path: Path) -> None:
     path = tmp_path / "metadata.json"
     original = MetadataPayload(session_id="session-1", stack_id="stack-1")
     path.write_text(original.model_dump_json())
-    updated = update_metadata_anchor(path, original, "abc123")
+    updated = update_metadata_anchor(path, original, "abc123", clone_sha="def456")
     assert updated.session_id == "session-1"
     assert updated.base_sha == "abc123"
+    assert updated.clone_sha == "def456"
 
 
 def test_update_metadata_anchor_preserves_extra_fields(tmp_path: Path) -> None:
@@ -45,14 +46,17 @@ def test_update_metadata_anchor_preserves_extra_fields(tmp_path: Path) -> None:
     original = _load_metadata(path)
     assert original is not None
 
-    updated = update_metadata_anchor(path, original, "abc123")
+    updated = update_metadata_anchor(path, original, "abc123", clone_sha="def456")
     saved = json.loads(path.read_text())
 
-    # Local on-disk schema uses `base_sha`. The wire-format remap to
-    # `head_sha` happens only at bundle-build time — see test_bundle.py.
+    # Local on-disk schema uses `base_sha` for the verification base and
+    # `clone_sha` for the remote checkout anchor. The wire-format remap of
+    # `clone_sha` to `head_sha` happens only at bundle-build time.
     assert updated.base_sha == "abc123"
+    assert updated.clone_sha == "def456"
     assert saved["prompt"] == "Keep this value"
     assert saved["base_sha"] == "abc123"
+    assert saved["clone_sha"] == "def456"
     assert "head_sha" not in saved
 
 
@@ -155,7 +159,7 @@ def test_checkpoint_rejects_stack_flag_when_session_exists(
             session_id="existing-session", stack_id="existing-stack"
         ).model_dump_json()
     )
-    (assertion_dir / "base_sha").write_text("a" * 40 + "\n")
+    (assertion_dir / "verify_base_sha").write_text("a" * 40 + "\n")
     (assertion_dir / "prompts").write_text(
         '{"ts": "2026-05-30T00:00:00Z", "text": "do the thing"}\n'
     )

{assertion_cli-0.5.11 → assertion_cli-0.5.13}/tests/test_session_start.py

@@ -66,7 +66,7 @@ def test_session_start_does_not_write_skill_or_agent_files(
     assert not (tmp_path / "AGENTS.md").exists()
 
 
-def test_session_start_ignores_assertion_state_but_keeps_seed_trackable(
+def test_session_start_resets_assertion_state_but_keeps_seed_trackable(
     tmp_path: Path, monkeypatch
 ) -> None:
     _init_repo(tmp_path)
@@ -75,7 +75,8 @@ def test_session_start_ignores_assertion_state_but_keeps_seed_trackable(
     existing_gitignore = "*.pyc\n"
     (tmp_path / ".gitignore").write_text(existing_gitignore)
     (tmp_path / ".assertion").mkdir()
-    (tmp_path / ".assertion" / "base_sha").write_text("local state\n")
+    (tmp_path / ".assertion" / "verify_base_sha").write_text("local state\n")
+    (tmp_path / ".assertion" / "old_file").write_text("old\n")
     (tmp_path / ".assertion" / "seed.py").write_text(
         "from assertion_seed import seed\n"
     )
@@ -87,8 +88,13 @@ def test_session_start_ignores_assertion_state_but_keeps_seed_trackable(
         "*.pyc\n\n# Assertion CLI local state\n.assertion/*\n!.assertion/seed.py\n"
     )
 
+    # Old state is cleared; seed.py is preserved.
+    assert not (tmp_path / ".assertion" / "old_file").exists()
+    assert (tmp_path / ".assertion" / "seed.py").exists()
+    assert (tmp_path / ".assertion" / "verify_base_sha").exists()
+
     ignored_state = subprocess.run(
-        ["git", "check-ignore", ".assertion/base_sha"],
+        ["git", "check-ignore", ".assertion/verify_base_sha"],
         cwd=tmp_path,
         capture_output=True,
     )
@@ -214,14 +220,13 @@ def test_session_start_falls_back_to_head_when_no_upstream(
 
     assert result.exit_code == 0
     assert "falling back to HEAD" in result.stderr
-    assert (tmp_path / ".assertion" / "base_sha").read_text().strip() == head_sha
+    assert (tmp_path / ".assertion" / "verify_base_sha").read_text().strip() == head_sha
 
 
-def test_session_start_records_merge_base_as_base(tmp_path: Path, monkeypatch) -> None:
-    """`asrt session start` pins the diff base to the branch merge-base.
+def test_session_start_records_merge_base_as_verify_base(tmp_path: Path, monkeypatch) -> None:
+    """`asrt session start` pins the verification base to the branch merge-base.
 
-    Every subsequent checkpoint/verify diffs against this SHA, so backend can
-    check out the upstream-visible base before applying the full diff.
+    Every subsequent checkpoint/verify diffs against this SHA.
     """
     _init_repo(tmp_path)
     monkeypatch.chdir(tmp_path)
@@ -237,7 +242,7 @@ def test_session_start_records_merge_base_as_base(tmp_path: Path, monkeypatch) -
     merge_base = _run_git(tmp_path, "merge-base", "HEAD", upstream)
     head_sha = _run_git(tmp_path, "rev-parse", "HEAD")
 
-    base_sha_path = tmp_path / ".assertion" / "base_sha"
+    base_sha_path = tmp_path / ".assertion" / "verify_base_sha"
     assert base_sha_path.exists()
     assert base_sha_path.read_text().strip() == merge_base
     assert merge_base != head_sha
@@ -252,4 +257,33 @@ def test_session_start_errors_when_repo_has_no_commits(
 
     result = runner.invoke(main.app, ["session", "start"])
     assert result.exit_code == 1
-    assert not (tmp_path / ".assertion" / "base_sha").exists()
+    assert not (tmp_path / ".assertion" / "verify_base_sha").exists()
+
+
+def test_session_start_from_explicit_ref(tmp_path: Path, monkeypatch) -> None:
+    """`--from` lets the user choose the verification base explicitly."""
+    _init_repo(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    verify_base = _run_git(tmp_path, "rev-parse", "HEAD")
+    _run_git(tmp_path, "commit", "--allow-empty", "-m", "local work")
+
+    result = runner.invoke(main.app, ["session", "start", "--from", verify_base])
+    assert result.exit_code == 0, result.stderr
+
+    assert (
+        tmp_path / ".assertion" / "verify_base_sha"
+    ).read_text().strip() == verify_base
+
+
+def test_session_start_from_ref_rejects_non_ancestor(
+    tmp_path: Path, monkeypatch
+) -> None:
+    """`--from` must point to an ancestor of HEAD."""
+    _init_repo(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    _run_git(tmp_path, "commit", "--allow-empty", "-m", "local work")
+    orphan = _run_git(tmp_path, "commit-tree", "HEAD^{tree}", "-m", "orphan")
+
+    result = runner.invoke(main.app, ["session", "start", "--from", orphan])
+    assert result.exit_code == 1
+    assert "not an ancestor of HEAD" in result.stderr

assertion_cli-0.5.11/templates/AGENTS.md

@@ -1,14 +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. Apply to every user turn, not just the first.
-2. **Checkpoint at trajectory-feedback moments** with `asrt checkpoint` — a handful across a feature build, not one per file.
-3. **Verify at completion** with `asrt verify`. Once it is clean, open a PR whose body embeds the hidden session marker from `asrt get-link`.
-
-See the skill file for the full rules, edge cases, and the exact PR command.

assertion_cli-0.5.11/tests/test_new.py

@@ -1,142 +0,0 @@
-from __future__ import annotations
-
-import subprocess
-from pathlib import Path
-
-from typer.testing import CliRunner
-
-import main
-
-
-runner = CliRunner()
-
-_GIT_COMMIT_ENV = {
-    "GIT_AUTHOR_NAME": "T",
-    "GIT_AUTHOR_EMAIL": "t@t",
-    "GIT_COMMITTER_NAME": "T",
-    "GIT_COMMITTER_EMAIL": "t@t",
-    "PATH": "/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin",
-}
-
-
-def _run_git(repo: Path, *args: str) -> str:
-    result = subprocess.run(
-        ["git", *args],
-        cwd=repo,
-        capture_output=True,
-        check=True,
-        env={**_GIT_COMMIT_ENV, "HOME": str(repo)},
-        text=True,
-    )
-    return result.stdout.strip()
-
-
-def _init_repo(tmp_path: Path) -> str:
-    _run_git(tmp_path, "init")
-    _run_git(tmp_path, "commit", "--allow-empty", "-m", "init")
-    branch = _run_git(tmp_path, "rev-parse", "--abbrev-ref", "HEAD")
-    _run_git(tmp_path, "remote", "add", "origin", "http://example.com/repo.git")
-    _run_git(tmp_path, "update-ref", f"refs/remotes/origin/{branch}", "HEAD")
-    _run_git(tmp_path, "branch", "-u", f"origin/{branch}")
-    return _run_git(tmp_path, "merge-base", "HEAD", f"origin/{branch}")
-
-
-def test_new_clears_run_state_and_records_merge_base(
-    tmp_path: Path,
-    monkeypatch,
-) -> None:
-    merge_base = _init_repo(tmp_path)
-    monkeypatch.chdir(tmp_path)
-
-    assertion_dir = tmp_path / ".assertion"
-    (assertion_dir / "screenshots" / "verification-1").mkdir(parents=True)
-    (assertion_dir / "metadata.json").write_text("{}")
-    (assertion_dir / "prompts").write_text("old prompt")
-    (assertion_dir / "checkpoint").write_text("old checkpoint")
-    (assertion_dir / "link").write_text("old link")
-    (assertion_dir / "verify_session_id").write_text("old verification")
-    (assertion_dir / "base_sha").write_text("old-base")
-    (
-        assertion_dir / "screenshots" / "verification-1" / "screenshot_000.png"
-    ).write_bytes(b"png")
-
-    result = runner.invoke(main.app, ["new"])
-
-    assert result.exit_code == 0, result.stderr
-    assert (assertion_dir / "base_sha").read_text() == merge_base + "\n"
-    assert not (assertion_dir / "metadata.json").exists()
-    assert not (assertion_dir / "prompts").exists()
-    assert not (assertion_dir / "checkpoint").exists()
-    assert not (assertion_dir / "link").exists()
-    assert not (assertion_dir / "verify_session_id").exists()
-    assert not (assertion_dir / "screenshots").exists()
-    assert "Recorded diff base" in result.stdout
-
-
-def test_new_succeeds_when_assertion_dir_missing(
-    tmp_path: Path,
-    monkeypatch,
-) -> None:
-    merge_base = _init_repo(tmp_path)
-    monkeypatch.chdir(tmp_path)
-
-    result = runner.invoke(main.app, ["new"])
-
-    assert result.exit_code == 0, result.stderr
-    assert (tmp_path / ".assertion" / "base_sha").read_text() == merge_base + "\n"
-
-
-def test_new_keeps_merge_base_after_local_head_changes(
-    tmp_path: Path,
-    monkeypatch,
-) -> None:
-    merge_base = _init_repo(tmp_path)
-    monkeypatch.chdir(tmp_path)
-
-    first_result = runner.invoke(main.app, ["new"])
-    assert first_result.exit_code == 0, first_result.stderr
-    assert (tmp_path / ".assertion" / "base_sha").read_text() == merge_base + "\n"
-
-    _run_git(tmp_path, "commit", "--allow-empty", "-m", "second")
-    second_head = _run_git(tmp_path, "rev-parse", "HEAD")
-
-    second_result = runner.invoke(main.app, ["new"])
-
-    assert second_result.exit_code == 0, second_result.stderr
-    assert second_head != merge_base
-    assert (tmp_path / ".assertion" / "base_sha").read_text() == merge_base + "\n"
-
-
-def test_new_leaves_next_checkpoint_requiring_stack(
-    tmp_path: Path,
-    monkeypatch,
-) -> None:
-    _init_repo(tmp_path)
-    monkeypatch.chdir(tmp_path)
-
-    assertion_dir = tmp_path / ".assertion"
-    assertion_dir.mkdir()
-    (assertion_dir / "metadata.json").write_text("{}")
-    (assertion_dir / "prompts").write_text("old prompt")
-
-    result = runner.invoke(main.app, ["new"])
-
-    assert result.exit_code == 0, result.stderr
-    assert not (assertion_dir / "metadata.json").exists()
-
-
-def test_new_falls_back_to_head_when_no_upstream(
-    tmp_path: Path,
-    monkeypatch,
-) -> None:
-    """When no upstream tracking branch exists, fall back to HEAD instead of erroring."""
-    _run_git(tmp_path, "init")
-    _run_git(tmp_path, "commit", "--allow-empty", "-m", "init")
-    head_sha = _run_git(tmp_path, "rev-parse", "HEAD")
-    monkeypatch.chdir(tmp_path)
-
-    result = runner.invoke(main.app, ["new"])
-
-    assert result.exit_code == 0
-    assert "falling back to HEAD" in result.stderr
-    assert (tmp_path / ".assertion" / "base_sha").read_text().strip() == head_sha