assertion-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{assertion_cli-0.2.0 → assertion_cli-0.4.0}/PKG-INFO

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

{assertion_cli-0.2.0 → assertion_cli-0.4.0}/assertion_cli.egg-info/PKG-INFO

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

{assertion_cli-0.2.0 → assertion_cli-0.4.0}/assertion_cli.egg-info/SOURCES.txt

@@ -24,5 +24,4 @@ tests/test_init.py
 tests/test_link.py
 tests/test_main.py
 tests/test_prompt.py
-tests/test_session.py
-tests/test_stack_resolve.py
+tests/test_session.py

assertion_cli-0.4.0/bundle.py

@@ -0,0 +1,42 @@
+import io
+import json
+import zipfile
+
+from models import MetadataPayload
+
+ASSERTION_DIR_NAME = ".assertion"
+DIFF_ARCHIVE_PATH = "git.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`.
+
+    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.
+    """
+    payload = metadata.model_dump()
+    payload["head_sha"] = payload.pop("base_sha", None)
+    return json.dumps(payload, indent=2) + "\n"
+
+
+def build_bundle(
+    *,
+    metadata: MetadataPayload,
+    diff_text: str,
+    prompts_text: str,
+    checkpoint_text: str,
+) -> bytes:
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, mode="w", compression=zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr(METADATA_ARCHIVE_PATH, _metadata_wire_json(metadata))
+        zf.writestr(PROMPTS_ARCHIVE_PATH, prompts_text)
+        zf.writestr(CHECKPOINT_ARCHIVE_PATH, checkpoint_text)
+        zf.writestr(DIFF_ARCHIVE_PATH, diff_text)
+    return buf.getvalue()

{assertion_cli-0.2.0 → assertion_cli-0.4.0}/git.py

@@ -37,73 +37,6 @@ def find_git_root(start_path: Path) -> Path:
     return Path(completed.stdout.strip())
 
 
-def get_diff_base_sha(repo_root: Path) -> str:
-    """Return the SHA the verifier should diff against — i.e. the most recent
-    commit reachable from BOTH local HEAD and some `refs/remotes/*` ref.
-
-    The verifier clones from GitHub and runs `git checkout <head_sha>` (see
-    backend/repo_analysis/clone.py). That checkout fails for any commit that
-    only exists locally — which is exactly what Codex Cloud produces when its
-    agent autocommits before `asrt checkpoint`. By picking the latest commit
-    that's on origin AND reachable from HEAD, the checkout always succeeds;
-    any local-only commits on top of that base flow through as part of the
-    diff (see `get_uncommitted_diff`), so the verifier still sees the full
-    state the agent built.
-
-    When HEAD itself is on a remote-tracking ref (no local commits),
-    `git merge-base HEAD <ref>` returns HEAD, so this collapses to the old
-    behavior with no diff growth.
-    """
-    try:
-        remote_refs = run_git_command(
-            repo_root, ["for-each-ref", "--format=%(refname:short)", "refs/remotes"]
-        )
-    except RuntimeError as exc:
-        exit_with_error(f"Failed to inspect remote refs: {exc}")
-
-    refs = [
-        ref for ref in remote_refs.splitlines() if ref and not ref.endswith("/HEAD")
-    ]
-    if not refs:
-        exit_with_error(
-            "No remote-tracking branches found. The verifier needs a commit "
-            "on origin to apply the diff onto — push at least one branch "
-            "(and `git fetch`) before running this command."
-        )
-
-    candidate_shas: list[str] = []
-    for ref in refs:
-        completed = subprocess.run(
-            ["git", "merge-base", "HEAD", ref],
-            cwd=repo_root,
-            capture_output=True,
-            text=True,
-            check=False,
-        )
-        if completed.returncode == 0:
-            sha = completed.stdout.strip()
-            if sha:
-                candidate_shas.append(sha)
-
-    if not candidate_shas:
-        exit_with_error(
-            "HEAD has no commits in common with any remote-tracking branch. "
-            "Push the branch (or its parent commits) to origin and retry."
-        )
-
-    best_sha = candidate_shas[0]
-    best_ts = -1
-    for sha in candidate_shas:
-        try:
-            ts = int(run_git_command(repo_root, ["log", "-1", "--format=%ct", sha]))
-        except (RuntimeError, ValueError):
-            continue
-        if ts > best_ts:
-            best_ts = ts
-            best_sha = sha
-    return best_sha
-
-
 def get_head_sha(repo_root: Path) -> str:
     try:
         return run_git_command(repo_root, ["rev-parse", "HEAD"])
@@ -120,40 +53,6 @@ def get_head_branch(repo_root: Path) -> str | None:
     return name if name and name != "HEAD" else None
 
 
-def get_origin_github_repo(repo_root: Path) -> str | None:
-    """Return the current repo's GitHub `owner/name` from origin, or None if not parseable.
-
-    Accepts the common remote URL forms:
-      git@github.com:owner/name(.git)?
-      https://github.com/owner/name(.git)?
-      ssh://git@github.com/owner/name(.git)?
-    """
-    try:
-        url = run_git_command(repo_root, ["remote", "get-url", "origin"]).strip()
-    except RuntimeError:
-        return None
-    if not url:
-        return None
-
-    if url.startswith("git@github.com:"):
-        path = url[len("git@github.com:") :]
-    elif url.startswith("ssh://git@github.com/"):
-        path = url[len("ssh://git@github.com/") :]
-    elif url.startswith("https://github.com/"):
-        path = url[len("https://github.com/") :]
-    elif url.startswith("http://github.com/"):
-        path = url[len("http://github.com/") :]
-    else:
-        return None
-
-    path = path.rstrip("/")
-    if path.endswith(".git"):
-        path = path[: -len(".git")]
-    if path.count("/") != 1 or not all(path.split("/")):
-        return None
-    return path
-
-
 def _build_untracked_diff(repo_root: Path, rel_path: str) -> str:
     completed = subprocess.run(
         [

{assertion_cli-0.2.0 → assertion_cli-0.4.0}/main.py

@@ -5,6 +5,7 @@ import re
 from datetime import datetime, timezone
 from pathlib import Path
 
+import httpx
 import typer
 
 from api import AssertionClient
@@ -12,21 +13,23 @@ from bundle import build_bundle
 from git import (
     exit_with_error,
     find_git_root,
-    get_diff_base_sha,
     get_head_branch,
+    get_head_sha,
     get_uncommitted_diff,
 )
 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,
     append_checkpoint_entry,
     continue_session,
     load_existing_session,
+    read_init_base_sha,
     start_new_session,
-    update_metadata_head,
+    update_metadata_anchor,
 )
 
 app = typer.Typer(help="Assertion CLI")
@@ -194,11 +197,26 @@ def init() -> None:
     the skill and knows to call `asrt`. `asrt checkpoint` refreshes the skill files on each
     run so they stay aligned with the installed CLI; `CLAUDE.md` / `AGENTS.md` are only
     touched here, never by checkpoint, so they're safe to track in git.
+
+    Also records the current HEAD SHA as the diff base for all future checkpoint/verify
+    calls in this repo. The base is what the backend `git checkout`s against before
+    applying the diff — capturing it once at init means later commands don't need to
+    rediscover it (which previously broke in sandboxes with no remote-tracking refs).
     """
     repo_root = find_git_root(Path.cwd())
     _refresh_skill_files(repo_root)
     _apply_activation_blocks(repo_root)
     _ensure_gitignore_excludes_assertion(repo_root)
+
+    base_sha = get_head_sha(repo_root)
+    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")
+    typer.echo(
+        f"Recorded diff base {base_sha[:12]} → {base_sha_path.relative_to(repo_root)}"
+    )
+
     typer.echo("")
     typer.echo("The coding agent will now follow the Assertion workflow:")
     typer.echo('  - asrt prompt "<msg>" on every user turn')
@@ -234,7 +252,7 @@ def checkpoint(
     stack: str | None = typer.Option(
         None,
         "--stack",
-        help="Force a new session against this stack ID. Overwrites any existing session.",
+        help="Stack ID for a new session. Required on the first checkpoint; rejected once a session exists.",
     ),
     continue_session_flag: bool = typer.Option(
         False,
@@ -247,11 +265,12 @@ def checkpoint(
 ) -> None:
     """Record a checkpoint.
 
-    With no flag, the CLI auto-continues the existing session if one is present,
-    otherwise starts a new session against the stack attached to this repo's
-    GitHub origin. Use `--continue` to fail fast when no session exists, or
-    `--stack <id>` to force a brand-new session (destructive — replaces any
-    in-flight session).
+    First checkpoint of a session requires `--stack <id>` — the agent picks
+    the stack from `asrt stacks` using its own judgment (folder name, branch,
+    code, README, etc.). Once a session exists, the stack is locked: pass no
+    flag (auto-continues) or `--continue` (fails fast if no session exists).
+    Passing `--stack` on a later checkpoint is rejected — sessions cannot be
+    re-anchored mid-flight.
     """
     if stack and continue_session_flag:
         typer.echo("ERROR: --stack and --continue are mutually exclusive.", err=True)
@@ -266,35 +285,43 @@ def checkpoint(
     _refresh_skill_files(repo_root)
 
     existing_metadata_path = repo_root / ASSERTION_DIR_NAME / METADATA_FILE_NAME
+    session_exists = existing_metadata_path.exists()
 
-    if continue_session_flag or (stack is None and existing_metadata_path.exists()):
-        # Either the caller asked to continue explicitly, OR they passed no
-        # flag and a session already exists (2nd+ checkpoint of the same
-        # session). In both cases continue rather than starting fresh — the
-        # alternative would silently destroy an in-flight session. To force a
-        # new session, pass --stack <id> or clear .assertion/ first (the
-        # post-verify prompt offers to do this).
+    if stack and session_exists:
+        # The stack is locked once a session is anchored to it. The agent
+        # should never re-anchor — a wrong-stack mid-session creates a split
+        # verification record. The user is the only one who resets sessions.
+        exit_with_error(
+            "This session is already anchored to a stack. Sessions cannot be "
+            "re-anchored mid-flight — drop the `--stack` flag and re-run "
+            '`asrt checkpoint "<message>"` to continue. The anchored stack '
+            "is recorded in .assertion/metadata.json."
+        )
+
+    if continue_session_flag or session_exists:
         ctx, metadata = continue_session(start_path=Path.cwd())
     else:
-        from session import resolve_stack_id_for_repo
-
-        resolved_stack = stack or resolve_stack_id_for_repo(repo_root)
-        ctx, metadata = start_new_session(
-            start_path=Path.cwd(), stack_id=resolved_stack
-        )
+        if stack is None:
+            exit_with_error(
+                "No session exists yet and no --stack given. Run `asrt stacks` "
+                "to see available stacks, pick one whose name/description fits "
+                "the work, then run:\n"
+                '  asrt checkpoint --stack <STACK_ID> "<progress message>"'
+            )
+        ctx, metadata = start_new_session(start_path=Path.cwd(), stack_id=stack)
 
     stack_id = metadata.stack_id
     assert stack_id is not None
 
     append_checkpoint_entry(ctx.checkpoint_path, message)
-    # `head_sha` here is the diff base — the latest commit on origin that's
-    # also reachable from local HEAD. Backend uses it as the checkout target
-    # before applying the diff; sending the actual local HEAD would break
-    # when the agent has uncommitted-to-origin commits (e.g. Codex Cloud).
-    base_sha = get_diff_base_sha(ctx.repo_root)
+    # Base SHA is whatever `asrt init` recorded for this repo. Backend uses
+    # it as the checkout target before applying the diff. Pinning it at init
+    # time (instead of rediscovering per command) means sandboxes without
+    # remote-tracking refs — e.g. Codex Cloud — still work.
+    base_sha = read_init_base_sha(ctx.assertion_dir)
     head_branch = get_head_branch(ctx.repo_root)
     diff_text = get_uncommitted_diff(ctx.repo_root, base_sha)
-    metadata = update_metadata_head(
+    metadata = update_metadata_anchor(
         ctx.metadata_path, metadata, base_sha, head_branch=head_branch
     )
 
@@ -342,17 +369,34 @@ def _load_verify_session_id(assertion_dir: Path) -> str:
     return content
 
 
+def _decode_screenshot(uri: str) -> tuple[bytes, str]:
+    """Resolve a screenshot reference to (image bytes, file extension).
+
+    The backend may hand back either an inline ``data:`` URI (legacy format)
+    or an http(s) download URL pointing at the files proxy (current format,
+    e.g. ``.../api/v0/files/download/<token>``). Support both so a format
+    change on the backend doesn't break status reporting.
+    """
+    if uri.startswith("data:") and "," in uri:
+        header, b64data = uri.split(",", 1)
+        ext = "jpeg" if "jpeg" in header else "png"
+        return base64.b64decode(b64data), ext
+
+    response = httpx.get(uri, timeout=30.0, follow_redirects=True)
+    response.raise_for_status()
+    content_type = response.headers.get("content-type", "").lower()
+    is_jpeg = "jpeg" in content_type or uri.lower().endswith((".jpg", ".jpeg"))
+    return response.content, "jpeg" if is_jpeg else "png"
+
+
 def _write_screenshots(
     assertion_dir: Path, session_id: str, screenshots: list[str]
 ) -> Path:
     screenshot_dir = assertion_dir / "screenshots" / session_id
     screenshot_dir.mkdir(parents=True, exist_ok=True)
     for idx, uri in enumerate(screenshots):
-        _, b64data = uri.split(",", 1)
-        ext = "jpeg" if "jpeg" in uri.split(",")[0] else "png"
-        (screenshot_dir / f"screenshot_{idx:03d}.{ext}").write_bytes(
-            base64.b64decode(b64data)
-        )
+        data, ext = _decode_screenshot(uri)
+        (screenshot_dir / f"screenshot_{idx:03d}.{ext}").write_bytes(data)
     return screenshot_dir
 
 
@@ -374,11 +418,12 @@ def verify(
     ctx, metadata = load_existing_session(Path.cwd())
     stack_id = metadata.stack_id
     assert stack_id is not None
-    # See checkpoint() for why we send the diff base rather than local HEAD.
-    base_sha = get_diff_base_sha(ctx.repo_root)
+    # See checkpoint() for why the base is the SHA `asrt init` recorded,
+    # not local HEAD.
+    base_sha = read_init_base_sha(ctx.assertion_dir)
     head_branch = get_head_branch(ctx.repo_root)
     diff_text = get_uncommitted_diff(ctx.repo_root, base_sha)
-    metadata = update_metadata_head(
+    metadata = update_metadata_anchor(
         ctx.metadata_path, metadata, base_sha, head_branch=head_branch
     )
 
@@ -451,8 +496,20 @@ def verify_status(
 
     terminal = payload.status in {SessionStatus.SUCCEEDED, SessionStatus.FAILED}
     screenshot_count = len(payload.screenshots)
+    screenshots_saved = False
     if terminal and payload.screenshots:
-        _write_screenshots(ctx.assertion_dir, session_id, payload.screenshots)
+        # Saving screenshots must never block the verdict. A backend format
+        # change or a transient download failure should degrade to a warning,
+        # not swallow a `succeeded`/`failed` status the caller is waiting on.
+        try:
+            _write_screenshots(ctx.assertion_dir, session_id, payload.screenshots)
+            screenshots_saved = True
+        except Exception as exc:  # noqa: BLE001 - never let screenshots hide the verdict
+            typer.echo(
+                f"warning: could not save screenshots ({exc}); "
+                "the verdict below is unaffected.",
+                err=True,
+            )
 
     if json_output:
         typer.echo(
@@ -473,7 +530,7 @@ def verify_status(
             typer.echo(payload.message)
         if payload.summary:
             typer.echo(f"\nSummary:\n{payload.summary}")
-        if terminal and payload.screenshots:
+        if screenshots_saved:
             typer.echo(
                 f"\nScreenshots ({screenshot_count}) saved to "
                 f".assertion/screenshots/{session_id}/"

{assertion_cli-0.2.0 → assertion_cli-0.4.0}/models.py

@@ -62,11 +62,22 @@ class ErrorResponse(BaseModel):
 
 
 class MetadataPayload(BaseModel):
+    """Local on-disk schema for `.assertion/metadata.json`.
+
+    `base_sha` is the diff base (the commit `asrt init` 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.
+    """
+
     model_config = ConfigDict(extra="allow")
 
     session_id: str
     stack_id: str | None = None
-    head_sha: str | None = None
+    base_sha: str | None = None
     head_branch: str | None = None
 
 

{assertion_cli-0.2.0 → assertion_cli-0.4.0}/pyproject.toml

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

{assertion_cli-0.2.0 → assertion_cli-0.4.0}/session.py

@@ -6,8 +6,6 @@ from api import AssertionClient
 from git import (
     exit_with_error,
     find_git_root,
-    get_diff_base_sha,
-    get_origin_github_repo,
 )
 from models import MetadataPayload, SessionContext, render_stack_list
 
@@ -15,13 +13,35 @@ ASSERTION_DIR_NAME = ".assertion"
 PROMPTS_FILE_NAME = "prompts"
 CHECKPOINT_FILE_NAME = "checkpoint"
 METADATA_FILE_NAME = "metadata.json"
+BASE_SHA_FILE_NAME = "base_sha"
+
+
+def read_init_base_sha(assertion_dir: Path) -> str:
+    """Return the diff base SHA recorded by `asrt init`.
+
+    Exits with a clear error if init hasn't been run or the file is empty.
+    The base SHA is the commit the backend `git checkout`s against before
+    applying the diff, so every checkpoint/verify must have it.
+    """
+    path = assertion_dir / BASE_SHA_FILE_NAME
+    if not path.exists():
+        exit_with_error(
+            "No diff base recorded for this repo. Run `asrt init` first — "
+            "it captures the HEAD SHA 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 init` to record the diff base."
+        )
+    return content
 
 
 def _require_repo_ready(start_path: Path) -> Path:
     repo_root = find_git_root(start_path)
-    # Fail fast here if no remote-reachable base exists. Result is discarded
-    # — callers re-compute at diff time, which is cheap.
-    get_diff_base_sha(repo_root)
+    # Fail fast if `asrt init` 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)
     return repo_root
 
 
@@ -101,50 +121,6 @@ def _stacks_hint() -> str:
         )
 
 
-def resolve_stack_id_for_repo(repo_root: Path) -> str:
-    """Pick the stack whose `repo` field matches the current repo's origin.
-
-    Exits with a clear error if zero or more than one stack matches. The
-    enforcement is here (in the CLI) so the coding agent does not have to
-    follow a compliance rule — the rule is mechanical.
-    """
-    owner_name = get_origin_github_repo(repo_root)
-    if owner_name is None:
-        exit_with_error(
-            "Could not determine this repo's GitHub `owner/name` from the `origin` "
-            "remote. Pass `--stack <id>` explicitly to override."
-        )
-
-    client = AssertionClient()
-    stacks = client.stacks()
-
-    if not stacks:
-        exit_with_error(
-            "No verification stacks exist in this workspace yet. Open the "
-            "Assertion web app, create a stack, and attach this repo "
-            f"(`{owner_name}`) to it. Then re-run the command."
-        )
-
-    matches = [s for s in stacks if s.repo.strip() == owner_name]
-
-    if len(matches) == 1:
-        return matches[0].id
-    if len(matches) == 0:
-        bound_repos = sorted({s.repo.strip() for s in stacks})
-        exit_with_error(
-            f"No verification stack is attached to this repo (`{owner_name}`)."
-            f" Other stacks in this workspace are attached to: {', '.join(bound_repos)}."
-            " Open the Assertion web app, choose a stack,"
-            " and attach this repo to it. Then re-run the command."
-        )
-    # More than one match — let the agent / user pick explicitly.
-    names = ", ".join(f"{s.name} ({s.id})" for s in matches)
-    exit_with_error(
-        f"Multiple stacks are attached to `{owner_name}`: {names}. "
-        "Pass `--stack <id>` to disambiguate."
-    )
-
-
 def start_new_session(
     *,
     start_path: Path,
@@ -209,14 +185,20 @@ def append_checkpoint_entry(checkpoint_path: Path, message: str) -> None:
         f.write(f"{normalized}\n\n")
 
 
-def update_metadata_head(
+def update_metadata_anchor(
     metadata_path: Path,
     metadata: MetadataPayload,
-    head_sha: str,
+    base_sha: str,
     head_branch: str | None = None,
 ) -> MetadataPayload:
+    """Refresh the per-session git anchor: diff base + branch name.
+
+    `base_sha` is the diff base (recorded by `asrt init`, 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.
+    """
     updated = metadata.model_copy(
-        update={"head_sha": head_sha, "head_branch": head_branch}
+        update={"base_sha": base_sha, "head_branch": head_branch}
     )
     metadata_path.write_text(updated.model_dump_json(indent=2) + "\n", encoding="utf-8")
     return updated

{assertion_cli-0.2.0 → assertion_cli-0.4.0}/templates/ACTIVATION.md

@@ -8,7 +8,7 @@ This repo uses the Assertion CLI (`asrt`) to track user intent and verify your w
 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. Use `asrt checkpoint "<summary>"` — the CLI auto-resolves the stack from this repo's GitHub origin on the first call and auto-continues the session on subsequent calls. A whole feature build is a handful of checkpoints, not one per file.
+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.
 
 Do not open a PR without a clean `asrt verify`.