assertion-cli 0.5.7__tar.gz → 0.5.9__tar.gz

{assertion_cli-0.5.7 → assertion_cli-0.5.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertion-cli
-Version: 0.5.7
+Version: 0.5.9
 Summary: CLI for the Assertion API
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -39,6 +39,8 @@ that set is `httpx`, `pydantic`, `python-dotenv`, and `typer`.
 After installation:
 
 ```bash
+asrt install                           # one-time onboarding: write skill files, AGENTS.md/CLAUDE.md pointer, .gitignore
+asrt session start                     # per work session: record the diff base (current HEAD)
 asrt new                               # reset local run state for a fresh session
 asrt stacks
 asrt checkpoint --stack <stack-id> "Implemented X\nUpdated Y"

{assertion_cli-0.5.7 → assertion_cli-0.5.9}/README.md

@@ -25,6 +25,8 @@ that set is `httpx`, `pydantic`, `python-dotenv`, and `typer`.
 After installation:
 
 ```bash
+asrt install                           # one-time onboarding: write skill files, AGENTS.md/CLAUDE.md pointer, .gitignore
+asrt session start                     # per work session: record the diff base (current HEAD)
 asrt new                               # reset local run state for a fresh session
 asrt stacks
 asrt checkpoint --stack <stack-id> "Implemented X\nUpdated Y"

{assertion_cli-0.5.7 → assertion_cli-0.5.9}/assertion_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertion-cli
-Version: 0.5.7
+Version: 0.5.9
 Summary: CLI for the Assertion API
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -39,6 +39,8 @@ that set is `httpx`, `pydantic`, `python-dotenv`, and `typer`.
 After installation:
 
 ```bash
+asrt install                           # one-time onboarding: write skill files, AGENTS.md/CLAUDE.md pointer, .gitignore
+asrt session start                     # per work session: record the diff base (current HEAD)
 asrt new                               # reset local run state for a fresh session
 asrt stacks
 asrt checkpoint --stack <stack-id> "Implemented X\nUpdated Y"

{assertion_cli-0.5.7 → assertion_cli-0.5.9}/assertion_cli.egg-info/SOURCES.txt

@@ -13,15 +13,17 @@ assertion_cli.egg-info/dependency_links.txt
 assertion_cli.egg-info/entry_points.txt
 assertion_cli.egg-info/requires.txt
 assertion_cli.egg-info/top_level.txt
+templates/AGENTS.md
 templates/SKILL.md
 templates/__init__.py
 tests/test_api.py
 tests/test_bundle.py
 tests/test_decision.py
 tests/test_git.py
-tests/test_init.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.py
+tests/test_session_start.py

{assertion_cli-0.5.7 → assertion_cli-0.5.9}/bundle.py

@@ -6,6 +6,7 @@ from models import MetadataPayload
 
 ASSERTION_DIR_NAME = ".assertion"
 DIFF_ARCHIVE_PATH = "git.diff"
+UNCOMMITTED_DIFF_ARCHIVE_PATH = "uncommitted.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"
@@ -30,6 +31,7 @@ def build_bundle(
     *,
     metadata: MetadataPayload,
     diff_text: str,
+    uncommitted_diff_text: str,
     prompts_text: str,
     checkpoint_text: str,
 ) -> bytes:
@@ -39,4 +41,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)
     return buf.getvalue()

assertion_cli-0.5.9/git.py

@@ -0,0 +1,199 @@
+import subprocess
+from pathlib import Path
+from typing import NoReturn, Sequence
+
+import typer
+
+
+def exit_with_error(message: str) -> NoReturn:
+    typer.echo(message, err=True)
+    raise typer.Exit(code=1)
+
+
+def run_git_command(
+    repo_root: Path, args: Sequence[str], *, preserve_stdout: bool = False
+) -> str:
+    completed = subprocess.run(
+        ["git", *args],
+        cwd=repo_root,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if completed.returncode != 0:
+        message = completed.stderr.strip() or completed.stdout.strip() or "git failed"
+        raise RuntimeError(message)
+    return completed.stdout if preserve_stdout else completed.stdout.strip()
+
+
+def find_git_root(start_path: Path) -> Path:
+    completed = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"],
+        cwd=start_path,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if completed.returncode != 0:
+        exit_with_error("Current directory is not inside a git repository.")
+    return Path(completed.stdout.strip())
+
+
+def get_head_sha(repo_root: Path) -> str:
+    try:
+        return run_git_command(repo_root, ["rev-parse", "HEAD"])
+    except RuntimeError as exc:
+        exit_with_error(f"Failed to get HEAD SHA: {exc}")
+
+
+def get_upstream_ref(repo_root: Path) -> str | None:
+    """Return the upstream tracking ref (e.g. ``origin/main``).
+
+    Tries HEAD's configured upstream first (``HEAD@{upstream}``). When the
+    branch has no upstream but the branch name itself resolves on the default
+    remote, falls back to ``origin/<branch>``. Returns ``None`` when neither
+    is available (detached HEAD, no remote, branch not pushed).
+    """
+    try:
+        return run_git_command(
+            repo_root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]
+        )
+    except RuntimeError:
+        pass
+
+    head_branch = get_head_branch(repo_root)
+    if head_branch is not None:
+        fallback = f"origin/{head_branch}"
+        try:
+            run_git_command(repo_root, ["rev-parse", "--verify", fallback])
+        except RuntimeError:
+            pass
+        else:
+            return fallback
+
+    return None
+
+
+def get_merge_base(repo_root: Path, upstream: str) -> str:
+    """Return the merge-base of ``HEAD`` and *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 get_head_branch(repo_root: Path) -> str | None:
+    """Return the current branch name, or None if HEAD is detached."""
+    try:
+        name = run_git_command(repo_root, ["rev-parse", "--abbrev-ref", "HEAD"])
+    except RuntimeError:
+        return None
+    return name if name and name != "HEAD" else None
+
+
+def _build_untracked_diff(repo_root: Path, rel_path: str) -> str:
+    completed = subprocess.run(
+        [
+            "git",
+            "diff",
+            "--no-index",
+            "--src-prefix=a/",
+            "--dst-prefix=b/",
+            "--",
+            "/dev/null",
+            rel_path,
+        ],
+        cwd=repo_root,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if completed.returncode not in (0, 1):
+        message = completed.stderr.strip() or completed.stdout.strip() or "git failed"
+        raise RuntimeError(message)
+    return completed.stdout
+
+
+# Paths the assertion-cli owns end-to-end. Excluded from the diff bundle so
+# reviewers don't flag our own bootstrap files as "unrelated changes" — they're
+# generated by `asrt install` and have nothing to do with the user's feature
+# work. CLAUDE.md / AGENTS.md are intentionally NOT in this list: `asrt install`
+# writes a small pointer block into them once at onboarding (meant to be
+# committed before work starts, so it never shows in a work-session diff), but
+# the rest of those files is the user's own and must flow through to reviewers.
+_ASSERTION_EXCLUDED_PATHSPECS = [
+    ":(exclude).assertion",
+    ":(exclude).claude/skills/assertion-cli",
+    ":(exclude).agents/skills/assertion-cli",
+]
+
+
+def _build_tracked_diff(repo_root: Path, base: str) -> str:
+    """``git diff <base>`` for tracked files, excluding assertion-owned paths."""
+    return run_git_command(
+        repo_root,
+        ["diff", base, "--", *_ASSERTION_EXCLUDED_PATHSPECS],
+        preserve_stdout=True,
+    )
+
+
+def _build_untracked_diffs(repo_root: Path) -> list[str]:
+    """Diff of every untracked (but non-ignored) file as a new-file diff."""
+    output = run_git_command(
+        repo_root,
+        [
+            "ls-files",
+            "--others",
+            "--exclude-standard",
+            "--",
+            *_ASSERTION_EXCLUDED_PATHSPECS,
+        ],
+    )
+    return [
+        _build_untracked_diff(repo_root, rel_path)
+        for rel_path in output.splitlines()
+        if rel_path
+    ]
+
+
+def _join_diffs(parts: list[str]) -> str:
+    parts = [_ensure_trailing_newline(p) for p in parts if p]
+    return "".join(parts)
+
+
+def get_uncommitted_diff(repo_root: Path) -> str:
+    """Build a diff of **only uncommitted** changes (staged + unstaged +
+    untracked).
+
+    ``git diff HEAD`` compares the working tree directly to ``HEAD``, so
+    local commits are excluded — only changes the agent hasn't committed yet
+    appear.
+    """
+    try:
+        tracked = _build_tracked_diff(repo_root, "HEAD")
+        untracked = _build_untracked_diffs(repo_root)
+        return _join_diffs([tracked, *untracked])
+    except RuntimeError as exc:
+        exit_with_error(f"Failed to collect uncommitted diff: {exc}")
+
+
+def get_full_diff(repo_root: Path, base_sha: str) -> str:
+    """Build a unified diff from ``base_sha`` to the current working tree.
+
+    ``git diff <base_sha>`` captures everything since the base commit —
+    local commits, staged changes, unstaged changes, and untracked files.
+    This is the diff the backend uses to reconstruct the full working state
+    (for terminal/browser sandboxes).
+    """
+    try:
+        tracked = _build_tracked_diff(repo_root, base_sha)
+        untracked = _build_untracked_diffs(repo_root)
+        return _join_diffs([tracked, *untracked])
+    except RuntimeError as exc:
+        exit_with_error(f"Failed to collect full diff: {exc}")
+
+
+def _ensure_trailing_newline(value: str) -> str:
+    return value if value.endswith("\n") else value + "\n"

{assertion_cli-0.5.7 → assertion_cli-0.5.9}/main.py

@@ -14,9 +14,11 @@ from bundle import build_bundle
 from git import (
     exit_with_error,
     find_git_root,
+    get_full_diff,
     get_head_branch,
-    get_head_sha,
+    get_merge_base,
     get_uncommitted_diff,
+    get_upstream_ref,
 )
 from link import load_link, save_link
 from models import CheckpointResponse, SessionStatus, render_stack_list
@@ -121,10 +123,11 @@ def _write_full_file(path: Path, content: str, repo_root: Path) -> None:
 
 
 def _refresh_skill_files(repo_root: Path) -> None:
-    """Write/refresh the assertion-owned skill files for each coding agent.
+    """Overwrite the assertion-owned skill files with the bundled template.
 
-    Safe to call on every checkpoint — these files are entirely ours; updating
-    them to match the installed CLI version cannot clobber user content.
+    Called only from `asrt install` (the one-time onboarding step), never on a
+    regular agent run — these files are entirely ours, so writing them to match
+    the installed CLI version cannot clobber user content.
 
     `.claude/skills/`  — Claude Code
     `.agents/skills/`  — Codex + Cursor (Cursor also accepts .cursor/skills/)
@@ -142,6 +145,55 @@ def _refresh_skill_files(repo_root: Path) -> None:
     )
 
 
+# Top-level agent instruction files. Unlike the skill files (which live in
+# agent-owned `*/skills/` dirs), these are user-owned docs that may already hold
+# the user's own content. So we inject an HTML-comment-delimited block rather
+# than overwriting the whole file, and replace just that block on re-install.
+_AGENT_DOC_FILES = ("AGENTS.md", "CLAUDE.md")
+_AGENT_BLOCK_START = "<!-- assertion-cli:start -->"
+_AGENT_BLOCK_END = "<!-- assertion-cli:end -->"
+
+
+def _agent_doc_block() -> str:
+    # No trailing newline: callers add exactly one when assembling the file so
+    # re-installs stay byte-idempotent (a block followed by the original
+    # post-marker text mustn't accumulate blank lines).
+    body = _load_template("AGENTS.md").strip("\n")
+    return f"{_AGENT_BLOCK_START}\n{body}\n{_AGENT_BLOCK_END}"
+
+
+def _upsert_agent_block(path: Path, block: str, repo_root: Path) -> None:
+    """Insert/replace the Assertion block in a user-owned agent doc, idempotently.
+
+    Creates the file from the block if missing; replaces an existing block in
+    place; otherwise appends the block, leaving the user's content untouched.
+    """
+    existing = path.read_text(encoding="utf-8") if path.exists() else ""
+
+    if _AGENT_BLOCK_START in existing and _AGENT_BLOCK_END in existing:
+        pre = existing.split(_AGENT_BLOCK_START, 1)[0]
+        post = existing.split(_AGENT_BLOCK_END, 1)[1]
+        prefix = pre.rstrip("\n") + "\n\n" if pre.strip() else ""
+        new_content = prefix + block + post
+    elif existing.strip():
+        new_content = existing.rstrip("\n") + "\n\n" + block + "\n"
+    else:
+        new_content = block + "\n"
+
+    if existing == new_content:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(new_content, encoding="utf-8")
+    typer.echo(f"Wrote {path.relative_to(repo_root)}")
+
+
+def _write_agent_docs(repo_root: Path) -> None:
+    """Write the assertion-cli pointer into the top-level agent instruction files."""
+    block = _agent_doc_block()
+    for name in _AGENT_DOC_FILES:
+        _upsert_agent_block(repo_root / name, block, repo_root)
+
+
 _ASSERTION_GITIGNORE_RULES = (".assertion/*", "!.assertion/seed.py")
 
 
@@ -175,33 +227,77 @@ def _ensure_gitignore_limits_assertion_state(repo_root: Path) -> None:
     )
 
 
-@app.command("init")
-def init() -> None:
-    """One-time bootstrap: install the assertion-cli skill files into this repo.
+@app.command("install")
+def install() -> None:
+    """One-time onboarding: scaffold the Assertion skill + agent docs into this repo.
 
-    Writes `.claude/skills/assertion-cli/SKILL.md` and
-    `.agents/skills/assertion-cli/SKILL.md`. Run this once after
-    `uv tool install assertion-cli` so the coding agent (Claude Code, Codex, Cursor)
-    auto-discovers the skill from its skills directory and knows to call `asrt`.
-    `asrt checkpoint` refreshes these skill files on each run so they stay aligned
-    with the installed CLI.
+    Run this once after `uv tool install assertion-cli`. It writes:
 
-    `init` never touches `CLAUDE.md` or `AGENTS.md`. Those are user-owned files;
-    the skill files are auto-discovered without an activation pointer, and editing
-    user-tracked docs would dirty their working tree and leak the assertion
-    bootstrap into the verification diff (which is anchored to the HEAD recorded
-    below).
+      - `.claude/skills/assertion-cli/SKILL.md` and
+        `.agents/skills/assertion-cli/SKILL.md` — the skill the coding agent
+        (Claude Code, Codex, Cursor) auto-discovers so it knows to call `asrt`.
+      - A short assertion-cli pointer block in the top-level `AGENTS.md` and
+        `CLAUDE.md`. These are user-owned, so the block is delimited by HTML
+        comments and re-installs replace just that block — any surrounding
+        content the user wrote is preserved.
+      - `.gitignore` rules that ignore local `.assertion/*` run state while
+        keeping committed seed hooks trackable.
 
-    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).
+    This is the onboarding step, not a per-run step: skill files are written
+    here, never on `asrt checkpoint`. After installing, run `asrt session start`
+    to record the diff base for a work session.
     """
     repo_root = find_git_root(Path.cwd())
     _refresh_skill_files(repo_root)
+    _write_agent_docs(repo_root)
+    _ensure_gitignore_limits_assertion_state(repo_root)
+
+    typer.echo("")
+    typer.echo(
+        "Assertion skill installed. To start a work session, run `asrt session start`."
+    )
+
+
+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.
+
+    Errors out when no upstream can be resolved (detached HEAD, no tracking
+    branch, branch not pushed to remote).
+    """
+    upstream = get_upstream_ref(repo_root)
+    if upstream is None:
+        exit_with_error(
+            "Cannot determine the diff base: no upstream tracking branch found.\n"
+            "Make sure you are on a branch that has been pushed to a remote "
+            "with a tracking branch configured, e.g.:\n"
+            "  git push -u origin <branch>\n"
+            "Or use an existing branch that tracks an upstream.",
+        )
+    return get_merge_base(repo_root, upstream)
+
+
+@session_app.command("start")
+def session_start() -> None:
+    """Record the merge-base with the upstream tracking branch as the diff base.
+
+    Unlike the old HEAD-based approach, the merge-base always exists on the
+    remote so the backend can check it out. Branches without a remote tracking
+    ref (detached HEAD, no upstream, not pushed) are rejected with a clear
+    message — run ``asrt session start`` from a branch with an upstream.
+
+    `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` /
+    `AGENTS.md`. It does ensure the `.gitignore` rules exist so the `.assertion`
+    state it writes below stays out of the user's commits.
+    """
+    repo_root = find_git_root(Path.cwd())
     _ensure_gitignore_limits_assertion_state(repo_root)
 
-    base_sha = get_head_sha(repo_root)
+    base_sha = _resolve_diff_base(repo_root)
     assertion_dir = repo_root / ASSERTION_DIR_NAME
     assertion_dir.mkdir(exist_ok=True)
     base_sha_path = assertion_dir / BASE_SHA_FILE_NAME
@@ -219,9 +315,9 @@ def init() -> None:
 
 @app.command("new")
 def new() -> None:
-    """Reset local Assertion run state and record current HEAD as the diff base."""
+    """Reset local Assertion run state and record the merge-base as the diff base."""
     repo_root = find_git_root(Path.cwd())
-    base_sha = get_head_sha(repo_root)
+    base_sha = _resolve_diff_base(repo_root)
     assertion_dir = repo_root / ASSERTION_DIR_NAME
     assertion_dir.mkdir(exist_ok=True)
 
@@ -296,12 +392,6 @@ def checkpoint(
 
     repo_root = find_git_root(Path.cwd())
 
-    # Refresh the assertion-owned skill files so the agent always loads the
-    # version that ships with the installed CLI. The CLI never writes
-    # CLAUDE.md / AGENTS.md — those are user-owned, and the skill files are
-    # auto-discovered without an activation pointer.
-    _refresh_skill_files(repo_root)
-
     existing_metadata_path = repo_root / ASSERTION_DIR_NAME / METADATA_FILE_NAME
     session_exists = existing_metadata_path.exists()
 
@@ -332,13 +422,10 @@ def checkpoint(
     assert stack_id is not None
 
     append_checkpoint_entry(ctx.checkpoint_path, message)
-    # 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)
+    diff_text = get_full_diff(ctx.repo_root, base_sha)
+    uncommitted_diff_text = get_uncommitted_diff(ctx.repo_root)
     metadata = update_metadata_anchor(
         ctx.metadata_path, metadata, base_sha, head_branch=head_branch
     )
@@ -346,6 +433,7 @@ def checkpoint(
     bundle_bytes = build_bundle(
         metadata=metadata,
         diff_text=diff_text,
+        uncommitted_diff_text=uncommitted_diff_text,
         prompts_text=ctx.prompts_path.read_text(encoding="utf-8"),
         checkpoint_text=message,
     )
@@ -436,11 +524,10 @@ def verify(
     ctx, metadata = load_existing_session(Path.cwd())
     stack_id = metadata.stack_id
     assert stack_id is not None
-    # 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)
+    diff_text = get_full_diff(ctx.repo_root, base_sha)
+    uncommitted_diff_text = get_uncommitted_diff(ctx.repo_root)
     metadata = update_metadata_anchor(
         ctx.metadata_path, metadata, base_sha, head_branch=head_branch
     )
@@ -448,6 +535,7 @@ def verify(
     bundle_bytes = build_bundle(
         metadata=metadata,
         diff_text=diff_text,
+        uncommitted_diff_text=uncommitted_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.7 → assertion_cli-0.5.9}/models.py

@@ -64,7 +64,7 @@ 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
+    `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

{assertion_cli-0.5.7 → assertion_cli-0.5.9}/pyproject.toml

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

{assertion_cli-0.5.7 → assertion_cli-0.5.9}/session.py

@@ -17,30 +17,32 @@ BASE_SHA_FILE_NAME = "base_sha"
 
 
 def read_init_base_sha(assertion_dir: Path) -> str:
-    """Return the diff base SHA recorded by `asrt init`.
+    """Return the diff base SHA recorded by `asrt session start`.
 
-    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.
+    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.
     """
     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."
+            "No diff base recorded for this repo. Run `asrt session start` "
+            "first — it captures the merge-base 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."
+            f"{path.name} is empty. Re-run `asrt session start` to record the "
+            "diff base."
         )
     return content
 
 
 def _require_repo_ready(start_path: Path) -> Path:
     repo_root = find_git_root(start_path)
-    # 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.
+    # 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)
     return repo_root
 
@@ -193,8 +195,8 @@ def update_metadata_anchor(
 ) -> 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
+    `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.
     """
     updated = metadata.model_copy(

assertion_cli-0.5.9/templates/AGENTS.md

@@ -0,0 +1,14 @@
+# 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.7 → assertion_cli-0.5.9}/templates/SKILL.md

@@ -14,7 +14,8 @@ This skill is operational, not advisory. Treat each rule as a hard requirement u
 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.
+- `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 current HEAD 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.
 
 **First command sequence for a new work session:**
 
@@ -118,7 +119,7 @@ When you pass `--stack`, briefly state which stack you chose and why ("Picked st
 | `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. |
 | `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 init` wasn't run. | Run `asrt init` and retry. |
+| `No diff 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. |
 
 ---

{assertion_cli-0.5.7 → assertion_cli-0.5.9}/tests/test_bundle.py

@@ -15,6 +15,7 @@ def test_build_bundle_writes_session_metadata() -> None:
     bundle_bytes = build_bundle(
         metadata=metadata,
         diff_text="diff --git a/file b/file",
+        uncommitted_diff_text="diff --git a/file b/file",
         prompts_text='{"ts": "2026-05-28T14:32:01Z", "text": "Do the thing"}\n',
         checkpoint_text="Checkpoint text",
     )
@@ -31,3 +32,10 @@ def test_build_bundle_writes_session_metadata() -> None:
 
         prompts_raw = zf.read(".assertion/prompts").decode("utf-8")
         assert '"text": "Do the thing"' in prompts_raw
+
+        # Both diffs are included in the bundle.
+        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