---
name: isurus-conventions
description: Use when working in the Isurus repository (or any repo identified as Isurus by the presence of `Isurus` in `README.md` or `cmd/isurus/`). Encodes Isurus-specific Mercurial conventions: non-publishing repo, bookmarks-as-PRs, commit message style, pre-PR Makefile checklist, opening PRs in the Isurus web UI.
---

# Isurus conventions (Mercurial overlay)

## When this applies

Use when working in the Isurus repository. Detect Isurus by:
- Repo root contains `cmd/isurus/`, or
- Top-level `README.md` contains the word `Isurus`, or
- Repo is cloned from `ssh://hg@hg.leafscale.com/leafscale/isurus`.

This skill is **purely additive**. The procedures live in `mercurial-basics`, `mercurial-bookmarks-and-prs`, `mercurial-sync-and-merge`, `mercurial-history-rewriting`, and `mercurial-finishing-a-branch`. This file supplies Isurus-specific values those procedures plug into.

## Repository facts

| Fact | Value |
|---|---|
| VCS | Mercurial 7.x (never git) |
| Clone URL | `ssh://hg@hg.leafscale.com/leafscale/isurus` |
| Long-lived branches | `default`, `stable` |
| Phase model | **Non-publishing** — pushed changesets stay `draft` until merged |
| Feature/PR mechanism | **Bookmarks** (push with `-B <name>`) |
| Forge | Isurus (web UI at `https://hg.leafscale.com/`) |

## Commit messages in this repo

- Imperative summary, **under 72 characters**.
- Prefix with a category: `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`, `scripts:`, `hgignore:`. Match what `hg log` shows for recent commits if uncertain.
- Body (optional) explains *why*; the diff shows *what*.
- One blank line between summary and body.
- **Never pass `-u`** to `hg commit` — identity is in `~/.hgrc`.

## Pre-PR check sequence

Run from the repo root, in this order:

```sh
make fmt        # gofmt — leaves no diff if all files are formatted
make vet        # go vet — catches suspicious constructs
make check      # full test suite against PostgreSQL test DB
```

`make check` requires the `isurus-test` database on localhost:
- DB name: `isurus-test`
- User: `isurus-test`
- Password: `isurus-test`

Override with `ISURUS_TEST_DSN`. See `make test-setup` for one-time DB creation.

Optional but recommended (skip if not installed):

```sh
make lint       # golangci-lint
```

The PR checklist from `CONTRIBUTING.md` (must all be true before opening PR):

- `make check` passes
- `go vet ./...` is clean
- Code is formatted (`make fmt`)
- New public functions have short godoc comments where non-obvious
- No new `TODO`/`FIXME` markers (fix or file an issue instead)
- Documentation updated if behavior or configuration changed
- Commit messages explain *why*

## Pull request flow

1. `hg push -B <bookmark>` to the canonical remote.
2. Open a PR in the Isurus web UI (`https://hg.leafscale.com/<owner>/<repo>`).
3. Title: same as the commit message summary.
4. Description: *why* + link to related issues.
5. Reviewer feedback → `hg amend` → `hg push -B <bookmark> -f`.

The non-publishing repo makes `-f` after amend the **expected** workflow, not a sign of trouble.

## What this overlay does NOT cover

- General Mercurial commands → `mercurial-basics`.
- Bookmark mechanics → `mercurial-bookmarks-and-prs`.
- Pull / merge / conflicts → `mercurial-sync-and-merge`.
- Amend / uncommit / phase rules → `mercurial-history-rewriting`.
- The end-to-end "finish a branch" sequence → `mercurial-finishing-a-branch`.

This file only changes the *values* those skills use (URLs, branch names, check commands). The procedures stay the same.