blumkin 0.2.0__tar.gz

blumkin-0.2.0/.cursor/rules/git-commit-identity.mdc

@@ -0,0 +1,156 @@
+---
+description: Commits and PRs attribute only the committer — no agent or machine co-authors
+alwaysApply: true
+---
+
+# Git commit identity
+
+Commits and pull requests must attribute **only** whoever is making the commit —
+their configured git `user.name` and `user.email`. Do not leak hostnames, Cursor,
+or other co-authors.
+
+## Commits
+
+- Use plain `git commit -m "…"` or a HEREDOC with **subject and body only**.
+- Do **not** add `Co-authored-by`, `Made-with: Cursor`, or any `--trailer` flags.
+- Do **not** append attribution lines to commit messages, even if Cursor defaults
+  would add them.
+- Do **not** pass `--no-gpg-sign` (or otherwise skip signing) when `commit.gpgsign`
+  is enabled.
+- After any commit (hooks / tooling may rewrite the message), inspect
+  `git show -s --format=%B HEAD` before push. If it contains `Co-authored-by:` or
+  `Made-with:`, **stop**, fix the message, and do not push until clean.
+- Prefer `git verify-commit HEAD` after signing commits; confirm GitHub shows the
+  commit as Verified once pushed.
+
+## Pull requests
+
+- Do **not** add `Co-authored-by` or `Made-with: Cursor` to `gh pr create --body`
+  or `gh pr edit --body`.
+
+## Git identity
+
+- Rely on git's configured author for the current committer (`git config user.name`
+  and `git config user.email`). Do not hardcode a specific name or email.
+- If `user.email` is unset, stop and ask the committer to configure git before
+  committing (avoid hostname fallback addresses like `user@machine.local`).
+- Also survey **effective** identity (env overrides beat config): compare
+  `git var GIT_AUTHOR_IDENT` and `git var GIT_COMMITTER_IDENT` to the approved
+  GitHub name/email. Reject machine-local addresses (e.g. `*.local`) and stop if
+  `GIT_AUTHOR_*`, `GIT_COMMITTER_*`, `EMAIL`, or `git commit --author` would produce
+  a different identity than configured.
+
+## Commit signing (GPG / SSH)
+
+At the **start of any session where the agent may commit**, survey whether commit
+signing is set up for the committer:
+
+1. `git config --get commit.gpgsign` should be `true` (global or local, as they intend).
+2. `git config --get user.signingkey` should be set (GPG key id, or SSH public key
+   path when `gpg.format` is `ssh`).
+3. Check `git config --get gpg.format` (and any repo-local override). For GPG
+   signing, prefer `openpgp` (or unset). If a leftover `gpg.format=ssh` is set
+   while `user.signingkey` is a GPG key id, Git will mis-treat the key — set
+   `gpg.format` to `openpgp` (or unset ssh) before committing.
+4. If `gpg.format` is `ssh`, confirm the public key path exists **and** the matching
+   private key is loaded (`ssh-add -L` should list it), or run a real signed-commit
+   probe. Otherwise confirm `gpg --list-secret-keys --keyid-format=long <signingkey>`
+   succeeds (secret present on **this** host).
+5. On Darwin (GPG): `pinentry-program` in `~/.gnupg/gpg-agent.conf` should point at an
+   existing binary (prefer `pinentry-mac` from Homebrew).
+6. Optional one-shot probe: `echo test | gpg --clearsign -u <KEYID>`. If it hangs or
+   fails in the agent TTY, tell the operator to unlock via GUI pinentry or finish the
+   commit in Terminal.app — agent terminals often cannot drive curses pinentry.
+7. GitHub Verified checks depend on signing format:
+   - **OpenPGP** (`gpg.format` is `openpgp` or unset): the **committer email** must
+     appear on the GPG key UID and be a **verified** email on the GitHub account
+     (same value as `git config user.email`). Optional list check:
+     `gh api user/gpg_keys` (needs `read:gpg_key`; `admin:gpg_key` also works). If the
+     API is unavailable, guide manual paste of `gpg --armor --export <KEYID>`.
+   - **SSH** (`gpg.format=ssh`): UID / `user/gpg_keys` do **not** apply. Confirm the
+     configured public key is registered on GitHub as a **Signing Key** (not only
+     Authentication) and that `ssh-add -L` lists the matching private key.
+
+If signing is missing or incomplete, **alert the committer** and surface setup
+instructions before committing (unless they explicitly opt out for a one-off).
+
+### Per-machine / personal vs work keys
+
+- Prefer a **separate signing key per machine** (or at least personal vs work). Do
+  **not** export a personal laptop’s secret key onto a corporate device.
+- Match `user.name` / `user.email` to the GitHub identity. For OpenPGP, put that same
+  verified email in the GPG UID; upload **that** public key to GitHub → Settings →
+  SSH and GPG keys. For SSH signing, upload the public key as a Signing Key.
+- When a work machine is retired, revoke/rotate that machine’s key on GitHub and
+  remove the local secret.
+
+### Passphrase
+
+- **Recommend using a passphrase** on the signing key (protects the secret at rest;
+  `gpg-agent` can cache it with `default-cache-ttl` / `max-cache-ttl`).
+- Do **not** suggest empty-passphrase keys “for agent convenience.”
+- Agent / non-TTY sessions usually cannot drive curses pinentry — use GUI
+  `pinentry-mac` (macOS) or commit from Terminal.app after unlocking once.
+
+### GPG key (macOS / Homebrew)
+
+```bash
+brew install gnupg pinentry-mac
+# If brew cannot link into /opt/homebrew/bin (ownership / permissions), fix Homebrew
+# ownership for that prefix or use the full $(brew --prefix)/bin path below.
+
+mkdir -p ~/.gnupg
+chmod 700 ~/.gnupg
+echo "pinentry-program $(brew --prefix)/bin/pinentry-mac" >> ~/.gnupg/gpg-agent.conf
+# optional passphrase cache (seconds), so you are not prompted every commit:
+# echo "default-cache-ttl 28800" >> ~/.gnupg/gpg-agent.conf
+# echo "max-cache-ttl 86400" >> ~/.gnupg/gpg-agent.conf
+gpgconf --kill gpg-agent
+
+gpg --full-generate-key
+# Choose RSA (or default), key size ≥ 3072, set an expiration, and use a passphrase.
+# UID email must be a GitHub-verified address matching git config user.email.
+gpg --list-secret-keys --keyid-format=long
+git config --global gpg.format openpgp
+git config --global user.signingkey <KEYID>
+git config --global commit.gpgsign true
+# Clear a leftover repo-local ssh signing override if present:
+# git config --unset gpg.format   # run inside the repo if it forced ssh
+gpg --armor --export <KEYID>
+# Upload the armored public key: GitHub → Settings → SSH and GPG keys → New GPG key
+
+# Sanity check (GUI pinentry should appear if the agent needs the passphrase):
+echo test | gpg --clearsign -u <KEYID>
+```
+
+### SSH signing (alternative)
+
+```bash
+git config --global gpg.format ssh
+git config --global user.signingkey ~/.ssh/id_ed25519.pub
+git config --global commit.gpgsign true
+ssh-add -L   # private key must be available via ssh-agent
+# Add the same public key on GitHub as a Signing Key (not only Authentication)
+```
+
+## Cursor CLI attribution (per machine)
+
+At the **start of any session where the agent may commit or open PRs**, read
+`~/.cursor/cli-config.json` (if present) and verify attribution is disabled:
+
+```json
+"attribution": {
+  "attributeCommitsToAgent": false,
+  "attributePRsToAgent": false
+}
+```
+
+If the file is missing, unreadable, or either flag is not `false`, **alert the
+committer** before committing and surface setup instructions — explain that Cursor
+will inject co-author trailers unless they fix their local config. Provide the
+exact keys to set (or create the file with the block above). Also remind them to
+disable **Settings → Git & PRs → Attribution** in the Cursor IDE (IDE and CLI
+settings are separate).
+
+Do not commit on their behalf until they acknowledge or fix the config (unless
+they explicitly opt out for a one-off commit).

blumkin-0.2.0/.cursor/rules/lexicographic-code-organization.mdc

@@ -0,0 +1,95 @@
+---
+description: Lexicographic code organization — public then private; sorted closed sets
+alwaysApply: true
+---
+
+# Lexicographic code organization
+
+**Default:** sort **ASCII lexicographically by name** whenever possible. **Insert** new
+definitions and closed-set members in sorted position — do not append at the bottom of a
+block.
+
+Keep language-standard import / `from … import` blocks at the top of the module (e.g. PEP 8
+for Python); they are not part of the public/private sorts below.
+
+## Module level
+
+Two blocks, in order:
+
+1. **Public** — module-level names **without** a leading `_`: constants (`ALL_CAPS`),
+   classes, module-level functions (`def` / `async def`), and other public bindings. Sort
+   **within this block** by name (ASCII).
+2. **Private** — module-level names **with** a leading `_` (helpers, module-private
+   constants, etc.). Sort **within this block** by name (ASCII).
+
+Public names are **not** interleaved with private names by strict global ASCII
+(`build_foo` stays in the public block even though `_` sorts before `b`).
+
+```python
+# public block (sorted)
+DEFAULT_TIMEOUT_S = 30
+class Widget: ...
+def build_status() -> None: ...
+
+# private block (sorted)
+def _epoch_to_iso_z(epoch: float) -> str: ...
+def _format_label(dt: datetime) -> str: ...
+```
+
+When adding a new `_helper`, insert it among the other `_` names — not after the public
+APIs and not at the end of the file unless it sorts last in the private block.
+
+## Inside a `class`
+
+Two blocks, in order:
+
+1. **Public** — class-level members whose names do **not** start with `_`, including
+   methods, `@property` getters, constants, nested classes, and other bindings. Treat
+   `async def` like `def`. Dunder methods (`__init__`, `__str__`, …) live in this block and
+   participate in the same lexicographic sort.
+2. **Private** — class-level members whose names start with `_` (single leading underscore),
+   including methods, properties, constants, nested classes, and other bindings. Sort
+   lexicographically within this block.
+
+```python
+class Example:
+  def __init__(self) -> None: ...
+  def __str__(self) -> str: ...
+  def close(self) -> None: ...
+  def fetch(self) -> None: ...
+
+  def _validate(self) -> None: ...
+```
+
+## Closed-set literals
+
+For **unordered** closed name sets, keep members in **ASCII lexicographic order** and insert
+new members in sorted position (do not append):
+
+- `frozenset({...})` / `set` literals of names
+
+For **order-sensitive** declarations, preserve declaration order when it is part of the
+contract (enum auto-values, iteration/serialization order, or user-visible sequencing). Sort
+lexicographically only when order is not significant:
+
+- Enum members — sort when values/iteration order are not contractual; otherwise keep
+  declaration order
+- Tuple / list constants of identifier-like strings — sort when order is not observable
+  externally; otherwise keep declaration order
+
+```python
+# good — unordered name set
+ALLOWED = frozenset({"alpha", "beta", "gamma"})
+
+# bad — unsorted / append-only unordered set
+ALLOWED = frozenset({"gamma", "alpha", "beta"})
+```
+
+## Other languages
+
+Apply the same **public-then-private, lexicographic within each block** idea elsewhere when
+organizing code (e.g. grouped `const` / `enum` members in TypeScript, export blocks in TS
+modules) unless a file already documents a different stable layout.
+
+Whole-file reorders of legacy modules are optional drive-by refactors; **new and moved APIs
+must follow this rule in the block they belong to.**

blumkin-0.2.0/.cursor/rules/local-live-graph-tests.mdc

@@ -0,0 +1,33 @@
+---
+description: Run live Graph/auth tests locally (CI mocks only)
+globs: src/blumkin/auth.py,src/blumkin/graph.py,src/blumkin/skills/**/*.py,tests/test_auth*.py,tests/test_live*.py
+alwaysApply: false
+---
+
+# Local live Graph / auth tests
+
+CI runs **mocked** unit tests only (`pytest -m 'not live'`). Silent refresh and real Graph reads are validated **on this machine**.
+
+Live means **real**: never verify with a skill that notifies others (no invites,
+sends, or chats). See `.cursor/rules/no-third-party-side-effects.mdc`.
+
+When changing auth, Graph client, calendar/mail/chat skills, or live/auth tests:
+
+1. Unit (same as CI):
+   ```bash
+   uv run pytest -m 'not live'
+   ```
+2. Live reads + forced access-token expiry → silent refresh:
+   ```bash
+   BLUMKIN_LIVE=1 uv run pytest -m live
+   ```
+   Requires config + token cache + auth record with a refresh token under
+   `~/.config/blumkin/` (or `BLUMKIN_CONFIG_DIR`). Do not commit those files.
+
+3. Smoke CLI after live green:
+   ```bash
+   blumkin auth status
+   blumkin calendar today --json
+   ```
+
+Do not skip step 2 for auth/token-cache changes: the live test force-expires the cached access token and asserts Graph still works and `auth status` shows a future expiry.

blumkin-0.2.0/.cursor/rules/main-worktree-off-limits.mdc

@@ -0,0 +1,38 @@
+---
+description: Never modify the primary (main) git worktree unless the user explicitly authorizes it
+alwaysApply: true
+---
+
+# Main worktree is off-limits
+
+The **primary clone** at the repo root (first line of `git worktree list`) is the **main worktree**. Do **not** modify it unless the user explicitly authorizes that in the current conversation.
+
+## Do all work in a stack worktree
+
+1. Run `~/work/ai/repository-helpers/scripts/dev/start-development --worktree <stack-name> --no-interactive`.
+2. `cd` into `.worktrees/<stack-name>-wt` before any implementation, tests, or git writes.
+3. Point tools at the stack worktree (`--dir`, working directory, file paths).
+
+## Forbidden on the main worktree (without explicit user authorization)
+
+- File edits, dependency installs, tests, builds, linters, formatters
+- `dep-updater --dir <repo-root>` (fast-forwards the primary clone and changes git state)
+- `gh stack …` / commits / checkouts / other git write operations
+- Leaving uncommitted changes or stray branches
+
+## Read-only on main is OK
+
+`git log`, `git show`, `gh pr view`, and reading files without writing are fine on the main worktree.
+
+## Investigating without polluting main
+
+Use a detached temporary worktree, not the primary clone:
+
+```bash
+git worktree add --detach /tmp/repo-inspect-<id> origin/main
+# ... read-only or isolated experiments ...
+git worktree remove --force /tmp/repo-inspect-<id>
+```
+
+`start-development` may sync the main worktree for environment setup; that does **not** grant permission to implement or run mutating commands there.
+

blumkin-0.2.0/.cursor/rules/no-secret-exposure.mdc

@@ -0,0 +1,46 @@
+---
+description: Never expose secrets in logs, PRs, tool output, or the repo
+alwaysApply: true
+---
+
+# No secret exposure (logs, PRs, repo)
+
+Coding agents must not leak secrets into **any** channel: shell/tool output,
+transcripts, PR/issue text, review replies, commits, fixtures, or docs.
+
+This complements CI secret-scan (detection after the fact). Prefer prevention.
+
+Org tracking / template sync: [repository-helpers#566](https://github.com/the-hcma/repository-helpers/issues/566).
+
+## Never print or paste
+
+- Client secrets, passwords, API keys, PATs, webhook secrets
+- Access / refresh tokens, MSAL / auth record JSON, private keys
+- Full contents of `~/.config/blumkin/config.toml`, `.env`, or token-cache files
+- Raw `Authorization` headers or Graph/MSAL error bodies that embed tokens
+
+## When inspecting local config
+
+- Prefer **allowlisted non-secret keys** only (`tenant_id`, `default_tz`,
+  `provider`, `wo1162425_scopes`, path existence flags).
+- Redact values that might be sensitive: `client_id = "(redacted)"`.
+- Do **not** `cat` / `type` whole config or env dumps “for debugging.”
+
+```bash
+# bad — may dump client_secret / tokens into the transcript
+cat ~/.config/blumkin/config.toml
+
+# good — keys only, redact known secret-ish values
+rg -n '^[a-z_]+' ~/.config/blumkin/config.toml | sed -E 's/(client_id|client_secret|google_oauth_client_file|.*token.*)\s*=.*/\1 = "(redacted)"/I'
+```
+
+## Repo / PR hygiene
+
+- Never commit secrets, `.msal_token_cache.json`, `.auth_record.json`, `.env`.
+- Never put secret values in PR titles, bodies, comments, or review replies.
+- Test fixtures use obvious fakes (`test-client`, `not-a-secret`).
+
+## If something already leaked
+
+Tell the operator to **rotate** the credential. Do **not** repeat the secret
+value in chat, logs, or GitHub.

blumkin-0.2.0/.cursor/rules/no-third-party-side-effects.mdc

@@ -0,0 +1,71 @@
+---
+description: Never let local verification reach other people (no invites, mail, or chats)
+alwaysApply: true
+---
+
+# Local verification must not reach other people
+
+blumkin acts as the operator against their real mailbox, calendar, and Teams. A
+verification run is not a sandbox: anything it sends is indistinguishable from the
+operator doing it by hand, lands in someone else's inbox or calendar, and cannot be
+recalled.
+
+**Never invoke a skill that notifies others in order to test, verify, demo, or
+reproduce something.** Do it only when the operator asks for that specific action
+in the current conversation, on the real recipients they named.
+
+## The trip-wire
+
+`blumkin skills list --json` marks every skill with `notifies_others`. Treat
+`notifies_others: true` as off-limits for verification. **The flag is
+authoritative** — the list below is a snapshot, so re-read the catalog rather
+than trusting it to stay complete. At the time of writing:
+
+- `calendar.accept` — sends a response to the organizer
+- `calendar.cancel` — sends cancellations to every attendee
+- `calendar.create` — invites attendees
+- `chat.delete` — every participant sees the message vanish
+- `chat.edit` — rewrites a message other people already read
+- `chat.send` — messages a person
+- `mail.send-draft` — sends mail
+
+To check the current set without trusting this list:
+
+```bash
+blumkin skills list --json | jq -r '.skills[] | select(.notifies_others) | .id'
+```
+
+Absence of the flag is not a blank cheque: `mail.draft`, `mail.update-draft`, and
+`mail.delete-draft` are safe because they stay in the operator's own mailbox, and
+that is the actual test — *does this reach anyone else?*
+
+## Verify with reads instead
+
+Reads cover most behavior, cost nothing, and reach no one:
+
+```bash
+blumkin calendar today --json
+blumkin calendar view --from YYYY-MM-DD --to YYYY-MM-DD --json
+blumkin mail list --folder sentitems --top 5 --json
+blumkin mail folders --json
+blumkin chat find --with "Name" --json
+blumkin chat last --with "Name" --n 3 --json
+```
+
+To exercise a write path, prefer one that is self-contained and reversible:
+create a draft, inspect it, delete it. Never promote that to a send.
+
+For anything genuinely unreachable without notifying someone, verify with mocked
+unit tests and say plainly that the live path was not exercised. An honest gap
+beats a real invitation.
+
+## If a notifying action is explicitly requested
+
+Confirm the recipients and the exact payload before running it, pass `--yes`
+knowingly rather than reflexively, and never widen the recipient list to make a
+test more convincing.
+
+## Free/busy and other people's data
+
+`calendar.freebusy` reads other people's availability. It notifies no one, so it
+is fine — but do not spray it across colleagues to generate test fixtures.

blumkin-0.2.0/.cursor/rules/pr-ship-and-review.mdc

@@ -0,0 +1,125 @@
+---
+description: Ship a PR end-to-end — local gates, submit, agent review loop, operator email
+alwaysApply: true
+---
+
+# PR ship, agent review, and operator email
+
+When the user asks to **ship**, **submit**, **open a PR**, or **follow the flow**, run this
+sequence in a **stack worktree** (never the primary clone). Read `.github/stacking-tool` and
+`.cursor/rules/stacking-tool.mdc` before creating branches or submitting.
+
+Helper scripts live in **repository-helpers** (canonical agent review loop):
+
+```bash
+rh="${REPOSITORY_HELPERS_DIR:-$HOME/work/ai/repository-helpers}"
+"${rh}/scripts/wait-for-agent-review" …
+"${rh}/scripts/trigger-agent-review" …
+```
+
+Configure `~/.config/agent-review.env` from `${rh}/etc/agent-review.env.example` (`AGENT_REVIEW_REPORT_TO`, SMTP).
+
+<!-- pr-ship-canonical-skill: https://github.com/the-hcma/repository-helpers/blob/main/.cursor/skills/ship-and-review/SKILL.md -->
+<!-- pr-ship-canonical-rule: https://github.com/the-hcma/repository-helpers/blob/main/.cursor/rules/pr-ship-and-review.mdc -->
+
+**Canonical playbook (read first):** This file is a consumer summary. Exit codes,
+early-complete semantics, quota chains, and triage details are maintained in
+repository-helpers and may change between releases.
+
+Agents **must** read the canonical Skill before running the agent review loop:
+
+- **GitHub (`main`):** https://github.com/the-hcma/repository-helpers/blob/main/.cursor/skills/ship-and-review/SKILL.md
+- **Local clone (when `${rh}` is synced to `main`):** `${rh}/.cursor/skills/ship-and-review/SKILL.md`
+
+When this summary and the canonical Skill disagree, follow the canonical Skill.
+
+## 1. Local quality gates (all must pass before submit)
+
+Run this repository's quality gates from the stack worktree (tests, linters, etc.).
+
+## 2. Commit and submit
+
+Only after §1 quality gates pass. **Read** `.github/stacking-tool` (`graphite` or `gh-stack`)
+and follow `.cursor/rules/stacking-tool.mdc` — do not mix backends on the same stack.
+
+```bash
+# When marker is graphite (apply-fix comments the inactive backend):
+# gt create <stack>/<topic> -m 'feat: …'   # or gt modify -m '…'
+# gt submit --publish --no-interactive
+
+# When marker is gh-stack:
+gh stack init <stack>/<topic>   # or gh stack add for a higher layer
+git add -A && git commit -m 'feat: …'
+gh stack submit --auto --open --remote origin
+```
+
+Wait for CI:
+
+```bash
+"${rh}/scripts/dev/post-pr-submission-checks" --pr <n>
+```
+
+If stderr shows `NOTE: GITHUB_RATE_LIMIT_*`, the helpers are waiting on GitHub API
+quota reset — let them finish (do not treat as a hard local failure mid-wait).
+
+Patch title/body if stale: `gh pr edit <n> --title … --body …`
+
+## 3. Agent review loop
+
+> **Reply before resolve (required):** For every valid agent review thread (Copilot, Bugbot, CodeRabbit, …), post an **on-thread human reply** as the authenticated operator **before** resolving. Exit code **3** means threads **lack a human reply** — resolving without replying is non-compliant.
+
+**Prerequisites:** `gh auth` must be set up for the operator running the loop. Copy
+`${rh}/etc/agent-review.env.example` to `~/.config/agent-review.env` with
+`AGENT_REVIEW_REPORT_TO` and SMTP before `complete`. `complete_ready: true` is
+reported by `"${rh}/scripts/wait-for-agent-review" check --pr <n>` (or `status`)
+JSON when CI is green and agent review threads are clear.
+
+Prefer the built-in loop:
+
+```bash
+"${rh}/scripts/wait-for-agent-review" loop --pr <n>
+```
+
+**Early complete:** when all threads are addressed, CI is green, there is **no** pending requested
+Copilot/Bugbot review, and CodeRabbit’s workflow is **not** running, the loop finishes — no
+mandatory idle dwell. **12h PR cap** (`AGENT_REVIEW_PR_TIMEOUT`) when review cycles never
+converge (exit **6** give-up). Per-agent quota caches skip exhausted agents (CodeRabbit, Copilot,
+Bugbot).
+
+**CodeRabbit is on_push:** a new push starts CodeRabbit — never post `@coderabbitai review`.
+If quota-limited, wait the cooldown with feedback polls (issue #369; default poll **60s**) +
+grace (default **60s**); only then, if still no real review on head, the loop may post a
+one-shot `@coderabbitai full review`. When CodeRabbit says wait, do not re-ask until
+`retry_after`. Rate-limit stubs are not reviews. Mid-cooldown pending
+feedback wakes the loop (exit **3**).
+
+When `loop` exits **3**, triage each unaddressed agent thread:
+
+1. Fix in the worktree when actionable (or skip with a brief on-thread reason).
+2. **Reply on-thread** as the authenticated human:
+   ```bash
+   "${rh}/scripts/wait-for-agent-review" reply-thread --thread-id <PRRT_…> --body 'Fixed in abc1234: …'
+   ```
+3. **Resolve only after step 2:**
+   ```bash
+   "${rh}/scripts/wait-for-agent-review" resolve-thread --thread-id <PRRT_…>
+   ```
+   Or batch: `"${rh}/scripts/wait-for-agent-review" resolve-addressed --pr <n>` (requires an existing human reply per thread).
+
+**Never** resolve via raw GraphQL/API without an on-thread human reply first.
+
+Then push fixes, re-run `"${rh}/scripts/dev/post-pr-submission-checks" --pr <n>`, and start the next loop iteration.
+
+When `check` reports `complete_ready: true`:
+
+```bash
+"${rh}/scripts/wait-for-agent-review" complete --pr <n>
+```
+
+`complete_ready` requires an agent sign-off on the current head (not a bare CodeRabbit
+commit status / rate-limit stub). This emails `AGENT_REVIEW_REPORT_TO`. It does **not**
+run `gh pr review --approve` (self-approve is skipped; merge stays an explicit operator step).
+
+Do **not** add `merge-it` unless the user explicitly confirms. Org merge path is
+GitHub auto-merge (`gh pr merge --auto --squash` / Enable auto-merge) when the
+operator asks to merge.

blumkin-0.2.0/.cursor/rules/pre-pr-checks.mdc

@@ -0,0 +1,67 @@
+---
+description: Block PR submit until pre-pr-checks pass; format before check; no truncated output
+alwaysApply: true
+---
+
+# Pre-PR checks (required)
+
+`pre-pr-checks` lives in **repository-helpers**, not in this repo. Resolve the
+clone once:
+
+```bash
+rh="${REPOSITORY_HELPERS_DIR:-$HOME/work/ai/repository-helpers}"
+```
+
+`pre-pr-checks` resolves its target from `$PWD`, so it audits **this** repo when
+run from a feature worktree here. The `submit-stack` wrapper does **not** — it
+resolves the repo from its own path and would submit the repository-helpers
+clone, so consumers submit with a bare `gh stack submit` / `gt submit`.
+
+Before submitting a PR:
+
+1. Run **`"${rh}/scripts/dev/pre-pr-checks"`** from this repo's feature worktree
+   (must exit 0), then submit with bare **`gh stack submit --auto`** or
+   **`gt submit`** per this repo's `.github/stacking-tool` marker, from the same
+   worktree. Do **not** use `"${rh}/scripts/dev/submit-stack"` from here.
+
+2. Do **not** submit if pre-pr-checks failed or was skipped. A skipped job is
+   allowed **only** when the user has approved it for this PR: pass
+   `PRE_PR_CHECKS_SKIP=job1,job2` (never a silent skip) and record the skipped
+   jobs and the reason in the PR **Test plan**.
+
+3. In the PR **Test plan**, note that `"${rh}/scripts/dev/pre-pr-checks"` passed
+   (paste the final `==> pre-pr-checks passed` line from the full run).
+
+4. Scripts must not leave changes on the **primary (main) worktree**.
+
+## Apply formatters before check (required)
+
+`pre-pr-checks` is **check-only** by default (e.g. `ruff format --check`, `cargo fmt -- --check`).
+After review-fix edits — especially string literals — **apply** formatters first, then run the gate:
+
+```bash
+# Python (match CI paths; adjust for the repo)
+uv run ruff format .
+# Rust
+cargo fmt --all
+# Then the gate
+"${rh}/scripts/dev/pre-pr-checks"
+# Or apply + check in one shot (mutates the worktree):
+"${rh}/scripts/dev/pre-pr-checks" --fix
+```
+
+Commit any format-only diff before submit. Do **not** treat a green `pytest` / `ruff check` /
+partial job as a pre-PR pass.
+
+## No truncated pre-PR output
+
+Do **not** pipe `pre-pr-checks` to `tail` / `head`. Require exit **0** and the final
+`==> pre-pr-checks passed` line from the full run.
+
+```bash
+# ❌ Truncated — hides failures above the last few lines
+"${rh}/scripts/dev/pre-pr-checks" 2>&1 | tail -8
+
+# ✅ Full output + exit status
+"${rh}/scripts/dev/pre-pr-checks"
+```

blumkin-0.2.0/.cursor/rules/read-agents-and-rules.mdc

@@ -0,0 +1,21 @@
+---
+description: On every new agent session, read AGENTS.md and .cursor/rules before acting
+alwaysApply: true
+---
+
+# Session start: read AGENTS.md and project rules
+
+At the **start of every new agent session** (before implementing, editing, or
+answering from assumed conventions), actively load project guidance:
+
+1. **Read** `AGENTS.md` at the repository root when it exists (use the Read tool;
+   do not rely only on auto-injected snippets).
+2. **List** `.cursor/rules/*.mdc` and **read** each rule that applies to this
+   session — at minimum every `alwaysApply: true` rule, plus any glob-matched
+   rules for files you will touch.
+
+Do this on the first turn of a new conversation even if some guidance already
+appears in context — confirm the on-disk files are what you follow.
+
+If `AGENTS.md` is missing, note that and continue with `.cursor/rules/` only.
+Do not invent org conventions that are not in those files.