tiny-pki 0.1.0__tar.gz

tiny_pki-0.1.0/.agents/rules/git-commit-identity.md

@@ -0,0 +1,117 @@
+---
+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.
+
+## Pre-submit verification
+
+Before **`submit-stack`** / **`ship-and-review`**, every non-merge commit on the stack branch ahead of `main` / `origin/main` must pass local **`git verify-commit`**. After push, confirm GitHub shows **Verified** on the PR commits tab (or `gh api repos/{owner}/{repo}/commits/<sha> --jq .commit.verification.verified`).
+
+`scripts/dev/pre-pr-checks` runs the **`verified-commits`** job for that range. It checks both the **signature** (`reason=local` / `reason=github`) and the **message attribution** (`reason=trailer`, matched case-insensitively): a `Co-authored-by:`, `Made-with:`, or non-committer `Signed-off-by:` trailer, or a whole-line `[🤖 ]Generated with [Name](url)` footer (anchored to that exact shape — prose elsewhere in the body that merely discusses the phrase or emoji is not flagged); or an author email matching a known agent identity — `opencode@users.noreply.github.com`, the `claude`/`cursoragent`/`devin` localparts and their known domains (bounded so real human names like "claudette" don't collide), or any other `*@users.noreply.github.com` address that differs from the committer's own (a fully agent-authored-and-committed commit is still caught: the specific agent patterns are not exempted just because author equals committer). Do not submit if it fails with `ERROR: UNVERIFIED_COMMIT`. Fix signing setup (see below) or amend the message and recommit. Escape hatches: `PRE_PR_CHECKS_SKIP=verified-commits` skips the whole job; `PRE_PR_CHECKS_ALLOW_COAUTHOR=email1,email2` allowlists a specific email as a real human identity for the rare case the operator explicitly wants it — a `Co-authored-by:` trailer, or an author email from a rebased/cherry-picked teammate commit — use only when the operator asked for it, not to bypass a failing check.
+
+## 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).

tiny_pki-0.1.0/.agents/rules/github-api-throttle.md

@@ -0,0 +1,19 @@
+---
+description: Every gh call site, agent or first-party code, must run through scripts/gh-api
+alwaysApply: true
+---
+
+# GitHub API rate-limit throttle
+
+Every `gh` call site — PR / issue triage, review replies, CI polling, `gh api`, `gh pr` / `gh issue` reads and writes, and any first-party script or library function in this repo that shells out to `gh` — **must** run through the throttled wrapper, never `gh` directly:
+
+```
+"${REPOSITORY_HELPERS_DIR:-$HOME/work/ai/repository-helpers}/scripts/gh-api" <gh args…>
+```
+
+so GitHub primary **and** secondary rate-limit backoff is automatic. A direct `gh` call 403s hard once the secondary limiter trips. First-party library code that already runs inside a bash process may instead source `scripts/lib/github-api-rate-limit` and call `github_api_exec_with_rate_limit_retry` directly — the same underlying backoff, without a redundant child-script fork per call.
+
+Full rationale, the two conforming shapes, the known cross-process quota gap (repository-helpers#664), exemptions (`auth`, prompts, `--web`), and `scripts/gh-api --help` (the SSOT) — the canonical rule in repository-helpers:
+
+<!-- github-api-throttle-canonical: https://github.com/the-hcma/repository-helpers/blob/main/.agents/rules/github-api-throttle.md -->
+https://github.com/the-hcma/repository-helpers/blob/main/.agents/rules/github-api-throttle.md

tiny_pki-0.1.0/.agents/rules/github-content-formatting.md

@@ -0,0 +1,19 @@
+---
+description: Format agent-authored GitHub issue/PR bodies and comments so they render correctly (blank lines + no hand-wrapped paragraphs)
+alwaysApply: true
+---
+
+# GitHub content formatting (agent-authored)
+
+Agent-authored issue bodies, PR descriptions, and PR/review comments must render correctly on GitHub: separate paragraphs and list items with a blank line, and write one physical line per paragraph — GitHub's issue/PR/comment renderer treats a lone `\n` as a **visible hard break**, unlike the file/blob renderer's soft-break-as-space.
+
+Write multi-paragraph or multi-line-list bodies to a temp file and post with `--body-file <path>`, never an inline `--body "..."` string with embedded `\n` escapes. Lint before posting:
+
+```bash
+"${REPOSITORY_HELPERS_DIR:-$HOME/work/ai/repository-helpers}/scripts/lint-github-markdown" <path>
+```
+
+Full authoring rules, the pre-flight linter, and `scripts/gh-issue` — the canonical rule in repository-helpers:
+
+<!-- github-content-formatting-canonical: https://github.com/the-hcma/repository-helpers/blob/main/.agents/rules/github-content-formatting.md -->
+https://github.com/the-hcma/repository-helpers/blob/main/.agents/rules/github-content-formatting.md

tiny_pki-0.1.0/.agents/rules/no-secret-exposure.md

@@ -0,0 +1,34 @@
+---
+description: Never leak secrets into logs, transcripts, PRs, commits, or fixtures
+alwaysApply: true
+---
+
+# No secret exposure
+
+Never leak secrets into shell/tool/transcript logs, PR/issue text, review replies, commits, fixtures, or docs. Complements CI secret-scan (prevention vs detection). See repository-helpers#566.
+
+## Never print or paste
+
+Do **not** print passwords, API keys, PATs, webhook/client secrets, tokens, private keys, Fernet/master keys; full `.env` / `config.toml` / token-cache / auth-record dumps; or `Authorization` headers with tokens.
+
+## Inspecting config
+
+Prefer allowlisted non-secret keys **or** path-existence only; redact sensitive values. Do **not** `cat` whole configs.
+
+```bash
+# bad
+cat .env
+# good
+test -f .env
+rg -n '^(APP_ENV|LOG_LEVEL)=' .env
+```
+
+Same idea for `~/.config/*/config.toml`, token-cache, and auth-record files: existence or allowlisted keys only — not denylist `sed` of a full dump.
+
+## Commits and fixtures
+
+Never commit secrets, `.env`, or private config. Never put secrets in PR text. Fixtures use obvious fakes only.
+
+## If leaked
+
+Tell the operator to **rotate** the credential. Do **not** repeat the secret in logs, replies, or follow-ups.

tiny_pki-0.1.0/.agents/rules/pr-ship-and-review.md

@@ -0,0 +1,102 @@
+---
+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/.agents/skills/ship-and-review/SKILL.md -->
+<!-- pr-ship-canonical-rule: https://github.com/the-hcma/repository-helpers/blob/main/.agents/rules/pr-ship-and-review.md -->
+
+**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/.agents/skills/ship-and-review/SKILL.md
+- **Local clone (when `${rh}` is synced to `main`):** `${rh}/.agents/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.

tiny_pki-0.1.0/.agents/rules/pre-pr-checks.md

@@ -0,0 +1,53 @@
+---
+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 marker-aware command (not `"${rh}/scripts/dev/submit-stack"`).
+
+Before submitting a PR:
+
+1. Run **`"${rh}/scripts/dev/pre-pr-checks"`** from this repo's feature worktree (must exit 0), then submit from the same worktree with the marker-aware bare command: **`gh stack submit --auto`** when `.github/stacking-tool` is `gh-stack`. When the marker is `graphite`, follow `.agents/rules/stacking-tool.md` / the Graphite skill (do not paste a Graphite-only submit into this rule). 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"
+```

tiny_pki-0.1.0/.agents/rules/read-agents-and-rules.md

@@ -0,0 +1,15 @@
+---
+description: On every new agent session, read AGENTS.md and .agents/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** `.agents/rules/*.md` 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. `.cursor/rules/*.mdc` files are Cursor injection shims only (frontmatter + pointer to the matching `.agents/rules/` file); do not treat the shim body as the rule.
+
+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 `.agents/rules/` only. Do not invent org conventions that are not in those files.

tiny_pki-0.1.0/.agents/rules/remote-timeouts-retries.md

@@ -0,0 +1,50 @@
+---
+description: All remote/network I/O must use explicit timeouts and bounded retries
+alwaysApply: true
+---
+
+# Remote timeouts and retries
+
+Any code that talks to a network peer (HTTP APIs, OAuth token endpoints, webhooks, package indexes, `gh`/`curl` helpers, cloud SDKs, etc.) must not hang indefinitely and must not retry without a bound. See repository-helpers#570.
+
+## Timeouts (required)
+
+- Set an **explicit timeout** on every remote call (connect + read, or a single overall deadline the library supports).
+- Prefer the product's shared HTTP client / config timeout knob when one exists. Defaults must be finite and documented. Never leave library defaults that mean "wait forever."
+- Agent / shell wrappers that hit the network should use the helpers' `--timeout` / `run_command … --timeout` patterns when available.
+- For GitHub API work, honor rate-limit / secondary-limit waits (`GITHUB_API_RATE_LIMIT` / documented cooldown helpers) rather than spinning.
+
+## Retries (required when retrying)
+
+- Retries are for **transient** failures only (timeouts, 429, 502/503/504, reset).
+- Cap attempts (small fixed `N`, typically 2–5) **or** a total retry budget.
+- Back off between attempts (exponential with jitter when practical). Honor `Retry-After` when the peer sends it.
+- Do **not** retry non-idempotent writes unless the API contract is safe (dedupe keys / explicit idempotency). Prefer fail fast on 4xx except 408/429.
+- Log or surface a clear timeout/retry exhaustion error — never spin silently.
+
+## Product-specific
+
+Wire timeouts through the repo's shared HTTP client / config knob. Do not add one-off unbounded clients beside that shared path.
+
+## Anti-patterns
+
+```python
+# bad — no timeout
+requests.get(url)
+httpx.get(url)
+client.execute()  # SDK call with no timeout / retry policy
+
+# bad — unbounded retry
+while True:
+    try:
+        return call()
+    except TimeoutError:
+        continue
+```
+
+```python
+# good — timeout from config + bounded retries
+http.timeout = httpx.Timeout(timeout_s, connect=min(30.0, timeout_s))
+# or: run_command "label" --timeout 20 -- curl …
+request_with_retries(call, max_attempts=3, retry_after_header=True)
+```

tiny_pki-0.1.0/.agents/rules/repo-practices-after-config-change.md

@@ -0,0 +1,48 @@
+---
+description: Run github-repo-lint after repo config or workflow changes
+globs:
+  - .agents/rules/**
+  - .agents/skills/**
+  - .cursor/rules/**
+  - .github/**
+  - pnpm-workspace.yaml
+  - release-please-config.json
+  - .release-please-manifest.json
+  - scripts/lib/repo-practices-workflows/**
+  - web/pnpm-workspace.yaml
+alwaysApply: false
+---
+
+# Repo practices lint after config changes
+
+When you edit **repo-practices-sensitive** paths — workflows, dependabot, Release Please config, pnpm release age, org agent rules/skills, `.github/ci/*`, or canonical workflow templates under `scripts/lib/repo-practices-workflows/` — **before submit**:
+
+## 1. Audit (required)
+
+From a synced **repository-helpers** clone (or this repo when you are in it):
+
+```bash
+scripts/github-repo-lint --repo OWNER/NAME --suggest --strict-onboarding
+```
+
+Resolve `OWNER/NAME` from `git remote get-url origin`. When not in repository-helpers, use `${REPOSITORY_HELPERS_DIR:-$HOME/work/ai/repository-helpers}/scripts/github-repo-lint`.
+
+Fix every `FAIL` before merge. Treat `SUGGEST` lines as follow-ups unless they block your change (e.g. missing `--apply-fix` merge settings when adding Release Please).
+
+## 2. GitHub-side fixes
+
+When adding **Release Please**, changing **merge/release settings**, or adopting org workflow templates, also run (mutates GitHub repo settings; run from the target clone when queuing workflow PRs):
+
+```bash
+scripts/github-repo-lint --repo OWNER/NAME --apply-fix
+```
+
+## 3. uv + Release Please jsonpath
+
+Copy `scripts/lib/repo-practices-workflows/release-please-uv-lock-extra-files.snippet.json` into `release-please-config.json` `extra-files`. The jsonpath **must** use `@.name.value`, not plain `@.name` — otherwise Release Please silently skips `uv.lock` ([release-please#2561](https://github.com/googleapis/release-please/issues/2561)).
+
+## 4. PR test plan
+
+Note that repo-practices lint passed (or list `--apply-fix` steps taken) in the PR **Test plan**.
+
+`scripts/dev/pre-pr-checks` runs this audit automatically when the branch diff touches workflow/config paths (detect-first `repo-practices-lint` job). Cursor rule edits alone do not trigger pre-pr (the audit reads GitHub, not your local tree).

tiny_pki-0.1.0/.agents/rules/stacking-tool.md

@@ -0,0 +1,46 @@
+---
+description: Choose Graphite vs GitHub Stacked PRs from .github/stacking-tool
+alwaysApply: true
+---
+
+# Stacking tool preference
+
+Before creating branches or submitting/restacking PRs, **read** `.github/stacking-tool` (single line: `graphite` or `gh-stack`). Missing or invalid values: **stop and ask** — do not guess.
+
+<!-- stacking-tool-canonical-graphite-skill: https://github.com/the-hcma/repository-helpers/blob/main/.agents/skills/graphite/SKILL.md -->
+<!-- stacking-tool-canonical-gh-stack-skill: https://github.com/the-hcma/repository-helpers/blob/main/.agents/skills/gh-stack/SKILL.md -->
+
+Canonical skills live in **repository-helpers** (not copied into this repo):
+
+- **Graphite:** https://github.com/the-hcma/repository-helpers/blob/main/.agents/skills/graphite/SKILL.md
+- **gh-stack:** https://github.com/the-hcma/repository-helpers/blob/main/.agents/skills/gh-stack/SKILL.md
+
+Local clone (when `${REPOSITORY_HELPERS_DIR:-$HOME/work/ai/repository-helpers}` is synced):
+
+- `${REPOSITORY_HELPERS_DIR}/.agents/skills/graphite/SKILL.md`
+- `${REPOSITORY_HELPERS_DIR}/.agents/skills/gh-stack/SKILL.md`
+
+## `graphite`
+
+- Follow the Graphite skill above (`gt create` / `gt submit` / `gt restack`).
+- Prefer repository-helpers `scripts/dev/submit-stack` when available in that clone.
+
+## `gh-stack`
+
+- Follow the gh-stack skill (non-interactive: `view --json`, `submit --auto --open`, named `init`/`add`).
+- Prefer repository-helpers `scripts/dev/submit-stack` / `scripts/dev/ship-and-review` when available (they dispatch via `scripts/lib/stacking-tool`).
+- **Do not** mix with `gt create` / `gt submit` / `gt restack` on the same stack.
+
+## Marker cutover checklist
+
+When flipping `.github/stacking-tool` (or landing an MQ/`gh-stack` cutover PR):
+
+1. Update `AGENTS.md` stacking/merge guidance to match the new marker (and GitHub auto-merge: `gh pr merge --auto --squash` — not `merge-it`).
+2. Rewrite `.agents/rules/pr-ship-and-review.md` submit block to the marker-aware template (copy via `github-repo-lint --apply-fix`, or from `${REPOSITORY_HELPERS_DIR}/scripts/lib/repo-practices-agents/rules/pr-ship-and-review.md` / https://github.com/the-hcma/repository-helpers/blob/main/scripts/lib/repo-practices-agents/rules/pr-ship-and-review.md; or ensure it documents both backends gated on the marker; keep a thin `.cursor/rules/pr-ship-and-review.mdc` shim).
+3. Delete root `GRAPHITE.md` when switching to `gh-stack` (canonical skill lives in repository-helpers).
+4. Keep `.agents/rules/stacking-tool.md` (+ Cursor shim) in sync with the consumer template.
+5. Re-run `scripts/github-repo-lint --repo OWNER/NAME --suggest --strict-onboarding` and fix stacking-docs consistency findings.
+
+## Unchanged regardless of marker
+
+Agent review, CI wait, and reply-before-resolve still follow `.agents/rules/pr-ship-and-review.md` and the canonical ship-and-review skill in repository-helpers.

tiny_pki-0.1.0/.cursor/rules/git-commit-identity.mdc

@@ -0,0 +1,7 @@
+---
+description: Commits and PRs attribute only the committer — no agent or machine co-authors
+alwaysApply: true
+---
+
+<!-- agents-rule-shim: git-commit-identity -->
+Canonical rule: [`.agents/rules/git-commit-identity.md`](../../.agents/rules/git-commit-identity.md)

tiny_pki-0.1.0/.cursor/rules/github-api-throttle.mdc

@@ -0,0 +1,7 @@
+---
+description: Every gh call site, agent or first-party code, must run through scripts/gh-api
+alwaysApply: true
+---
+
+<!-- agents-rule-shim: github-api-throttle -->
+Canonical rule: [`.agents/rules/github-api-throttle.md`](../../.agents/rules/github-api-throttle.md)

tiny_pki-0.1.0/.cursor/rules/github-content-formatting.mdc

@@ -0,0 +1,7 @@
+---
+description: Format agent-authored GitHub issue/PR bodies and comments so they render correctly (blank lines + no hand-wrapped paragraphs)
+alwaysApply: true
+---
+
+<!-- agents-rule-shim: github-content-formatting -->
+Canonical rule: [`.agents/rules/github-content-formatting.md`](../../.agents/rules/github-content-formatting.md)

tiny_pki-0.1.0/.cursor/rules/no-secret-exposure.mdc

@@ -0,0 +1,7 @@
+---
+description: Never leak secrets into logs, transcripts, PRs, commits, or fixtures
+alwaysApply: true
+---
+
+<!-- agents-rule-shim: no-secret-exposure -->
+Canonical rule: [`.agents/rules/no-secret-exposure.md`](../../.agents/rules/no-secret-exposure.md)

tiny_pki-0.1.0/.cursor/rules/pr-ship-and-review.mdc

@@ -0,0 +1,7 @@
+---
+description: Ship a PR end-to-end — local gates, submit, agent review loop, operator email
+alwaysApply: true
+---
+
+<!-- agents-rule-shim: pr-ship-and-review -->
+Canonical rule: [`.agents/rules/pr-ship-and-review.md`](../../.agents/rules/pr-ship-and-review.md)

tiny_pki-0.1.0/.cursor/rules/pre-pr-checks.mdc

@@ -0,0 +1,7 @@
+---
+description: Block PR submit until pre-pr-checks pass (shellcheck, tests, clean main wt)
+alwaysApply: true
+---
+
+<!-- agents-rule-shim: pre-pr-checks -->
+Canonical rule: [`.agents/rules/pre-pr-checks.md`](../../.agents/rules/pre-pr-checks.md)

tiny_pki-0.1.0/.cursor/rules/read-agents-and-rules.mdc

@@ -0,0 +1,7 @@
+---
+description: On every new agent session, read AGENTS.md and .agents/rules before acting
+alwaysApply: true
+---
+
+<!-- agents-rule-shim: read-agents-and-rules -->
+Canonical rule: [`.agents/rules/read-agents-and-rules.md`](../../.agents/rules/read-agents-and-rules.md)

tiny_pki-0.1.0/.cursor/rules/remote-timeouts-retries.mdc

@@ -0,0 +1,7 @@
+---
+description: All remote/network I/O must use explicit timeouts and bounded retries
+alwaysApply: true
+---
+
+<!-- agents-rule-shim: remote-timeouts-retries -->
+Canonical rule: [`.agents/rules/remote-timeouts-retries.md`](../../.agents/rules/remote-timeouts-retries.md)

tiny_pki-0.1.0/.cursor/rules/repo-practices-after-config-change.mdc

@@ -0,0 +1,17 @@
+---
+description: Run github-repo-lint after repo config or workflow changes
+globs:
+  - .agents/rules/**
+  - .agents/skills/**
+  - .cursor/rules/**
+  - .github/**
+  - pnpm-workspace.yaml
+  - release-please-config.json
+  - .release-please-manifest.json
+  - scripts/lib/repo-practices-workflows/**
+  - web/pnpm-workspace.yaml
+alwaysApply: false
+---
+
+<!-- agents-rule-shim: repo-practices-after-config-change -->
+Canonical rule: [`.agents/rules/repo-practices-after-config-change.md`](../../.agents/rules/repo-practices-after-config-change.md)

tiny_pki-0.1.0/.cursor/rules/stacking-tool.mdc

@@ -0,0 +1,7 @@
+---
+description: Choose Graphite vs GitHub Stacked PRs from .github/stacking-tool
+alwaysApply: true
+---
+
+<!-- agents-rule-shim: stacking-tool -->
+Canonical rule: [`.agents/rules/stacking-tool.md`](../../.agents/rules/stacking-tool.md)

tiny_pki-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Every change in this repo requires review from @thehcma.
+* @thehcma