assertion-cli 0.5.5__tar.gz → 0.5.6__tar.gz

{assertion_cli-0.5.5 → assertion_cli-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertion-cli
-Version: 0.5.5
+Version: 0.5.6
 Summary: CLI for the Assertion API
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -55,11 +55,10 @@ asrt verify-status                     # one-shot poll; loop with your own sleep
 
 That's it. The `Publish CLI to PyPI` workflow auto-triggers on pushes that
 change `cli/pyproject.toml`. It reads the version from the file, runs tests,
-builds, publishes to PyPI, pushes a `cli-v<version>` tag, and creates a
-GitHub Release with auto-generated notes.
+builds, publishes to PyPI, and pushes a `cli-v<version>` tag.
 
 If the version hasn't changed (e.g. you updated a dependency), the workflow
-skips publishing — only version bumps trigger a release.
+skips publishing — only version bumps trigger a publish.
 
 You can also trigger the workflow manually from the GitHub Actions UI — it
 reads the version from the current `pyproject.toml` on `main`.

{assertion_cli-0.5.5 → assertion_cli-0.5.6}/README.md

@@ -41,11 +41,10 @@ asrt verify-status                     # one-shot poll; loop with your own sleep
 
 That's it. The `Publish CLI to PyPI` workflow auto-triggers on pushes that
 change `cli/pyproject.toml`. It reads the version from the file, runs tests,
-builds, publishes to PyPI, pushes a `cli-v<version>` tag, and creates a
-GitHub Release with auto-generated notes.
+builds, publishes to PyPI, and pushes a `cli-v<version>` tag.
 
 If the version hasn't changed (e.g. you updated a dependency), the workflow
-skips publishing — only version bumps trigger a release.
+skips publishing — only version bumps trigger a publish.
 
 You can also trigger the workflow manually from the GitHub Actions UI — it
 reads the version from the current `pyproject.toml` on `main`.

{assertion_cli-0.5.5 → assertion_cli-0.5.6}/assertion_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertion-cli
-Version: 0.5.5
+Version: 0.5.6
 Summary: CLI for the Assertion API
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -55,11 +55,10 @@ asrt verify-status                     # one-shot poll; loop with your own sleep
 
 That's it. The `Publish CLI to PyPI` workflow auto-triggers on pushes that
 change `cli/pyproject.toml`. It reads the version from the file, runs tests,
-builds, publishes to PyPI, pushes a `cli-v<version>` tag, and creates a
-GitHub Release with auto-generated notes.
+builds, publishes to PyPI, and pushes a `cli-v<version>` tag.
 
 If the version hasn't changed (e.g. you updated a dependency), the workflow
-skips publishing — only version bumps trigger a release.
+skips publishing — only version bumps trigger a publish.
 
 You can also trigger the workflow manually from the GitHub Actions UI — it
 reads the version from the current `pyproject.toml` on `main`.

{assertion_cli-0.5.5 → assertion_cli-0.5.6}/assertion_cli.egg-info/SOURCES.txt

@@ -13,7 +13,6 @@ 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/ACTIVATION.md
 templates/SKILL.md
 templates/__init__.py
 tests/test_api.py

{assertion_cli-0.5.5 → assertion_cli-0.5.6}/git.py

@@ -80,8 +80,8 @@ def _build_untracked_diff(repo_root: Path, rel_path: str) -> str:
 # reviewers don't flag our own bootstrap files as "unrelated changes" — they're
 # generated/refreshed by `asrt init` and `asrt checkpoint` and have nothing to
 # do with the user's feature work. CLAUDE.md / AGENTS.md are intentionally
-# NOT in this list: those are user-owned files we only patch a marked
-# block into, so the user's other edits to them should still flow through.
+# NOT in this list: the CLI never writes them, so any edits there are the
+# user's own and should flow through to reviewers.
 _ASSERTION_EXCLUDED_PATHSPECS = [
     ":(exclude).assertion",
     ":(exclude).claude/skills/assertion-cli",

{assertion_cli-0.5.5 → assertion_cli-0.5.6}/main.py

@@ -2,7 +2,6 @@ import base64
 import importlib.metadata
 import importlib.resources
 import json
-import re
 import shutil
 from datetime import datetime, timezone
 from pathlib import Path
@@ -101,10 +100,6 @@ def stacks() -> None:
     typer.echo(render_stack_list(stack_list))
 
 
-ASSERTION_MARKER_BEGIN = "<!-- assertion-cli:begin -->"
-ASSERTION_MARKER_END = "<!-- assertion-cli:end -->"
-
-
 def _load_template(name: str) -> str:
     return (
         importlib.resources.files("assertion_cli_templates")
@@ -125,45 +120,6 @@ def _write_full_file(path: Path, content: str, repo_root: Path) -> None:
     typer.echo(f"Wrote {path.relative_to(repo_root)}")
 
 
-def _apply_marked_block(path: Path, body: str, repo_root: Path) -> None:
-    """Idempotently insert/update an assertion-marked block in a markdown file.
-
-    Existing content outside the markers is preserved exactly.
-    Silent on no-op; echoes only when a write actually happens.
-    """
-    marked_block = f"{ASSERTION_MARKER_BEGIN}\n{body}\n{ASSERTION_MARKER_END}\n"
-    pattern = re.compile(
-        re.escape(ASSERTION_MARKER_BEGIN)
-        + r".*?"
-        + re.escape(ASSERTION_MARKER_END)
-        + r"\n?",
-        re.DOTALL,
-    )
-
-    if path.exists():
-        current = path.read_text(encoding="utf-8")
-        if pattern.search(current):
-            # Replace via a callable so re.sub does NOT interpret backslash
-            # escapes (e.g. `\n`, `\g`) in the block — the activation template
-            # contains literal shell snippets like `printf '%s\n\n...'`, and a
-            # string replacement would mangle them, breaking init idempotency.
-            new_content = pattern.sub(lambda _match: marked_block, current)
-        else:
-            sep = (
-                ""
-                if current.endswith("\n\n")
-                else ("\n" if current.endswith("\n") else "\n\n")
-            )
-            new_content = current + sep + marked_block
-        if new_content != current:
-            path.write_text(new_content, encoding="utf-8")
-            typer.echo(f"Updated {path.relative_to(repo_root)}")
-    else:
-        path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(marked_block, encoding="utf-8")
-        typer.echo(f"Wrote {path.relative_to(repo_root)}")
-
-
 def _refresh_skill_files(repo_root: Path) -> None:
     """Write/refresh the assertion-owned skill files for each coding agent.
 
@@ -186,55 +142,55 @@ def _refresh_skill_files(repo_root: Path) -> None:
     )
 
 
-_GITIGNORE_ASSERTION_ENTRY = ".assertion/"
+_ASSERTION_GITIGNORE_RULES = (".assertion/*", "!.assertion/seed.py")
 
 
-def _ensure_gitignore_excludes_assertion(repo_root: Path) -> None:
-    """Append `.assertion/` to the repo's .gitignore if not already excluded.
-
-    `.assertion/` holds per-session state (prompts, checkpoint message,
-    metadata, screenshots) — purely local working data. Without this entry it
-    surfaces as untracked changes that `asrt checkpoint`'s diff collector
-    would otherwise bundle and send to the reviewers.
-    """
+def _ensure_gitignore_limits_assertion_state(repo_root: Path) -> None:
+    """Ignore local Assertion state while allowing committed seed hooks."""
     gitignore = repo_root / ".gitignore"
     existing = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
-    if any(
-        line.strip() in {".assertion", ".assertion/"} for line in existing.splitlines()
-    ):
+    lines = existing.splitlines()
+    stripped_lines = {line.strip() for line in lines}
+
+    missing_rules = [
+        rule for rule in _ASSERTION_GITIGNORE_RULES if rule not in stripped_lines
+    ]
+    if not missing_rules:
         return
-    prefix = "" if not existing or existing.endswith("\n") else "\n"
-    gitignore.write_text(
-        existing + prefix + _GITIGNORE_ASSERTION_ENTRY + "\n", encoding="utf-8"
-    )
-    typer.echo(
-        f"Updated {gitignore.relative_to(repo_root)} (added {_GITIGNORE_ASSERTION_ENTRY})"
-    )
 
+    added_lines = []
+    if "# Assertion CLI local state" not in stripped_lines:
+        added_lines.append("# Assertion CLI local state")
+    added_lines.extend(missing_rules)
 
-def _apply_activation_blocks(repo_root: Path) -> None:
-    """Insert/update the marked activation block in user-owned CLAUDE.md / AGENTS.md.
+    content = existing.rstrip()
+    if content:
+        content += "\n\n"
+    content += "\n".join(added_lines) + "\n"
 
-    Only called by `asrt init`. We deliberately do NOT call this on every checkpoint —
-    these files may be tracked in the user's git, and silently dirtying them on
-    every checkpoint is hostile. The block is a stable pointer to the skill file, so
-    re-running on every CLI upgrade isn't necessary.
-    """
-    activation_body = _load_template("ACTIVATION.md").strip()
-    _apply_marked_block(repo_root / "CLAUDE.md", activation_body, repo_root)
-    _apply_marked_block(repo_root / "AGENTS.md", activation_body, repo_root)
+    gitignore.write_text(content, encoding="utf-8")
+    typer.echo(
+        f"Updated {gitignore.relative_to(repo_root)} "
+        "(ignored .assertion/* except .assertion/seed.py)"
+    )
 
 
 @app.command("init")
 def init() -> None:
     """One-time bootstrap: install the assertion-cli skill files into this repo.
 
-    Writes `.claude/skills/assertion-cli/SKILL.md`, `.agents/skills/assertion-cli/SKILL.md`,
-    and the marked activation block in `CLAUDE.md` and `AGENTS.md`. Run this once after
-    `uv tool install assertion-cli` so the coding agent (Claude Code, Codex, Cursor) loads
-    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.
+    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.
+
+    `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).
 
     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
@@ -243,8 +199,7 @@ def init() -> None:
     """
     repo_root = find_git_root(Path.cwd())
     _refresh_skill_files(repo_root)
-    _apply_activation_blocks(repo_root)
-    _ensure_gitignore_excludes_assertion(repo_root)
+    _ensure_gitignore_limits_assertion_state(repo_root)
 
     base_sha = get_head_sha(repo_root)
     assertion_dir = repo_root / ASSERTION_DIR_NAME
@@ -342,9 +297,9 @@ 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. We deliberately do NOT touch
-    # CLAUDE.md / AGENTS.md here — those are user-owned and only updated
-    # by `asrt init`.
+    # 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

{assertion_cli-0.5.5 → assertion_cli-0.5.6}/pyproject.toml

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

{assertion_cli-0.5.5 → assertion_cli-0.5.6}/templates/SKILL.md

@@ -16,7 +16,7 @@ Before any `asrt` call:
 - You are inside a git repository.
 - `asrt init` has been run in this repo. It records the current HEAD as the diff base that every checkpoint/verify diffs against, and installs the skill files you are reading right now. If `asrt checkpoint` or `asrt verify` errors with "No diff base recorded", run `asrt init` and retry.
 
-**Starting a fresh session:** when beginning a new session, run `asrt new` first. This 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. Only the user should do this — it resets the session.
+**Starting a fresh session:** when beginning a new work session, check whether this repo may have previous Assertion state in `.assertion/`, then ask the user whether they want to clean up the previous session and start fresh. If the user says yes, run `asrt new` before any checkpoint or verify command. This 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. If the user says no, continue with the existing session state. 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.
 
@@ -193,12 +193,15 @@ 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.
+
 ---
 
 ## Quick reference
 
 ```
 asrt prompt "<message>"                       # every user turn, before anything else
+asrt new                                      # reset local run state only after user consent
 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

{assertion_cli-0.5.5 → assertion_cli-0.5.6}/tests/test_init.py

@@ -6,7 +6,6 @@ from pathlib import Path
 from typer.testing import CliRunner
 
 import main
-from main import ASSERTION_MARKER_BEGIN, ASSERTION_MARKER_END
 
 
 runner = CliRunner()
@@ -53,12 +52,137 @@ def test_init_writes_all_agent_destinations(tmp_path: Path, monkeypatch) -> None
     assert agents_skill.exists()
     assert agents_skill.read_text() == claude_skill.read_text()
 
-    # CLAUDE.md + AGENTS.md activation marker blocks
-    for filename in ["CLAUDE.md", "AGENTS.md"]:
-        body = (tmp_path / filename).read_text()
-        assert ASSERTION_MARKER_BEGIN in body
-        assert ASSERTION_MARKER_END in body
-        assert "Assertion verification" in body
+    # init must never create or touch user-owned CLAUDE.md / AGENTS.md — the
+    # skill files are auto-discovered, and editing user docs would leak the
+    # assertion bootstrap into the verification diff.
+    assert not (tmp_path / "CLAUDE.md").exists()
+    assert not (tmp_path / "AGENTS.md").exists()
+
+
+def test_init_ignores_assertion_state_but_keeps_seed_trackable(
+    tmp_path: Path, monkeypatch
+) -> None:
+    _init_repo(tmp_path)
+    monkeypatch.chdir(tmp_path)
+
+    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" / "seed.py").write_text("from assertion_seed import seed\n")
+
+    result = runner.invoke(main.app, ["init"])
+    assert result.exit_code == 0, result.stderr
+
+    assert (tmp_path / ".gitignore").read_text() == (
+        "*.pyc\n\n"
+        "# Assertion CLI local state\n"
+        ".assertion/*\n"
+        "!.assertion/seed.py\n"
+    )
+
+    ignored_state = subprocess.run(
+        ["git", "check-ignore", ".assertion/base_sha"],
+        cwd=tmp_path,
+        capture_output=True,
+    )
+    trackable_seed = subprocess.run(
+        ["git", "check-ignore", ".assertion/seed.py"],
+        cwd=tmp_path,
+        capture_output=True,
+    )
+    assert ignored_state.returncode == 0
+    assert trackable_seed.returncode == 1
+
+
+def test_init_creates_gitignore_for_assertion_state(tmp_path: Path, monkeypatch) -> None:
+    _init_repo(tmp_path)
+    monkeypatch.chdir(tmp_path)
+
+    result = runner.invoke(main.app, ["init"])
+    assert result.exit_code == 0, result.stderr
+
+    assert (tmp_path / ".gitignore").read_text() == (
+        "# Assertion CLI local state\n"
+        ".assertion/*\n"
+        "!.assertion/seed.py\n"
+    )
+
+
+def test_init_preserves_broad_assertion_gitignore_entry_while_adding_missing_rules(
+    tmp_path: Path, monkeypatch
+) -> None:
+    _init_repo(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / ".gitignore").write_text(".assertion/\n")
+
+    result = runner.invoke(main.app, ["init"])
+    assert result.exit_code == 0, result.stderr
+
+    assert (tmp_path / ".gitignore").read_text() == (
+        ".assertion/\n\n"
+        "# Assertion CLI local state\n"
+        ".assertion/*\n"
+        "!.assertion/seed.py\n"
+    )
+
+
+def test_init_adds_only_missing_assertion_gitignore_rules(
+    tmp_path: Path, monkeypatch
+) -> None:
+    _init_repo(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / ".gitignore").write_text(
+        "# Assertion CLI local state\n"
+        ".assertion/*\n"
+    )
+
+    result = runner.invoke(main.app, ["init"])
+    assert result.exit_code == 0, result.stderr
+
+    assert (tmp_path / ".gitignore").read_text() == (
+        "# Assertion CLI local state\n"
+        ".assertion/*\n\n"
+        "!.assertion/seed.py\n"
+    )
+
+
+def test_init_leaves_gitignore_unchanged_when_assertion_rules_exist(
+    tmp_path: Path, monkeypatch
+) -> None:
+    _init_repo(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    existing_gitignore = (
+        "*.pyc\n\n"
+        "# Assertion CLI local state\n"
+        ".assertion/*\n"
+        "!.assertion/seed.py\n"
+    )
+    (tmp_path / ".gitignore").write_text(existing_gitignore)
+
+    result = runner.invoke(main.app, ["init"])
+    assert result.exit_code == 0, result.stderr
+
+    assert (tmp_path / ".gitignore").read_text() == existing_gitignore
+
+
+def test_init_skill_prompts_before_new_session_cleanup(
+    tmp_path: Path, monkeypatch
+) -> None:
+    _init_repo(tmp_path)
+    monkeypatch.chdir(tmp_path)
+
+    result = runner.invoke(main.app, ["init"])
+    assert result.exit_code == 0, result.stderr
+
+    skill = (
+        tmp_path / ".agents" / "skills" / "assertion-cli" / "SKILL.md"
+    ).read_text()
+    assert "ask the user whether they want to clean up the previous session" in skill
+    assert "If the user says yes, run `asrt new` before any checkpoint" in skill
+    assert "Do not run `asrt new` without explicit user consent" in skill
+    assert "After the PR marker is confirmed" in skill
+    assert "clean up the completed Assertion session" in skill
 
 
 def test_init_is_idempotent(tmp_path: Path, monkeypatch) -> None:
@@ -71,8 +195,6 @@ def test_init_is_idempotent(tmp_path: Path, monkeypatch) -> None:
         for p in [
             ".claude/skills/assertion-cli/SKILL.md",
             ".agents/skills/assertion-cli/SKILL.md",
-            "CLAUDE.md",
-            "AGENTS.md",
         ]
     }
 
@@ -81,7 +203,16 @@ def test_init_is_idempotent(tmp_path: Path, monkeypatch) -> None:
         assert (tmp_path / rel).read_text() == before, rel
 
 
-def test_init_appends_to_existing_unmarked_files(tmp_path: Path, monkeypatch) -> None:
+def test_init_leaves_existing_activation_files_untouched(
+    tmp_path: Path, monkeypatch
+) -> None:
+    """init must not modify user-owned CLAUDE.md / AGENTS.md, byte for byte.
+
+    Previously init patched a marked activation block into these files. Because
+    the base SHA is recorded at init time, that edit then surfaced in every
+    checkpoint/verify diff as unrelated bootstrap noise. The skill files are
+    auto-discovered, so the activation block is unnecessary.
+    """
     _init_repo(tmp_path)
     monkeypatch.chdir(tmp_path)
 
@@ -93,34 +224,8 @@ def test_init_appends_to_existing_unmarked_files(tmp_path: Path, monkeypatch) ->
     result = runner.invoke(main.app, ["init"])
     assert result.exit_code == 0
 
-    claude_body = (tmp_path / "CLAUDE.md").read_text()
-    agents_body = (tmp_path / "AGENTS.md").read_text()
-    assert claude_body.startswith(existing_claude)
-    assert agents_body.startswith(existing_agents)
-    assert ASSERTION_MARKER_BEGIN in claude_body
-    assert ASSERTION_MARKER_BEGIN in agents_body
-
-
-def test_init_replaces_stale_marked_section(tmp_path: Path, monkeypatch) -> None:
-    _init_repo(tmp_path)
-    monkeypatch.chdir(tmp_path)
-
-    stale = (
-        "# Existing\n\n"
-        f"{ASSERTION_MARKER_BEGIN}\n"
-        "outdated content\n"
-        f"{ASSERTION_MARKER_END}\n\n"
-        "Custom instructions after.\n"
-    )
-    (tmp_path / "CLAUDE.md").write_text(stale)
-
-    runner.invoke(main.app, ["init"])
-
-    body = (tmp_path / "CLAUDE.md").read_text()
-    assert "outdated content" not in body
-    assert "# Existing" in body
-    assert "Custom instructions after." in body
-    assert "Assertion verification" in body
+    assert (tmp_path / "CLAUDE.md").read_text() == existing_claude
+    assert (tmp_path / "AGENTS.md").read_text() == existing_agents
 
 
 def test_init_requires_git_repo(tmp_path: Path, monkeypatch) -> None:

assertion_cli-0.5.5/templates/ACTIVATION.md

@@ -1,50 +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. **Log every user message:** run `asrt prompt "<exact text>"` before anything else, on every turn — it's the verifier's record of intent.
-2. **Checkpoint at trajectory-feedback moments**, not every change. First checkpoint: `asrt stacks`, pick the stack that fits, then `asrt checkpoint --stack <id> "<summary>"`; later ones drop `--stack` and auto-continue. A feature build is a handful of checkpoints.
-3. **Verify at completion** with `asrt verify`. If feedback requires changes, iterate and re-verify — do **not** drop back into the checkpoint loop. Once verify is clean, open a PR — and that PR **must** carry the hidden Assertion session marker (see below).
-
----
-
-## ⚠️ REQUIRED: every PR must embed the hidden session marker
-
-**This is the single most-missed step, and it is not optional.** A PR opened from an Assertion session that omits the marker cannot be linked back to its verification, so the work reads as unverified.
-
-The Assertion GitHub bot links a PR to its verification session by **branch name first**. When the branch name doesn't match the one you verified on (you renamed it, the head ref differs, etc.), the bot falls back to reading the marker. No marker → no fallback → no link.
-
-`asrt get-link` prints the marker as an HTML comment that GitHub hides from the rendered description but still delivers to the bot in the webhook payload:
-
-```
-<!-- assertion-session: https://app.tryassertion.com/sessions/<id> -->
-```
-
-**Open the PR with the marker embedded** — never paste the bare URL into the visible body; use the command so the format stays exact:
-
-```
-gh pr create --title "<title>" --body "$(printf '%s\n\n%s\n' '<one-paragraph why>' "$(asrt get-link)")"
-```
-
-If a PR already exists for the branch, add the marker instead of opening a new one:
-
-```
-gh pr edit --body "$(printf '%s\n\n%s\n' '<existing summary>' "$(asrt get-link)")"
-```
-
-**Then confirm it landed.** The marker won't show in the rendered description — that's expected — so verify it's in the raw body:
-
-```
-gh pr view --json body --jq .body | grep -q 'assertion-session:' && echo "marker present" || echo "MARKER MISSING — fix before continuing"
-```
-
----
-
-## Hard gates (do not bypass)
-- **No PR whose body omits the session marker.** If `asrt get-link` has nothing to return, you haven't verified yet — go back to rule 3.
-- **Confirm the marker after creating/editing the PR** with the `gh pr view` check above. Treat a missing marker as a blocking error, not a warning.