obelisk/CONTRIBUTING.md

# Contributing to Obelisk

Thanks for contributing. This document exists because most PRs that stall here
are not low-quality code — they pass lint, typecheck, and their own tests. They
stall on a small number of recurring failures that are easy to avoid once
someone names them.

Read the section for the area you are changing. The verification contract at the
bottom applies to every PR.

---

## Six things that decide whether a PR lands

**1. Run every sentence of your PR description end to end.**
The single most common failure is a capability that is advertised but
unreachable. If you describe a config option, use that option from the outermost
entry point before submitting. If you post a screenshot, the input in that
screenshot must be an input the code can actually handle.

**2. Write assertions in the words of the requirement, not the shape of the
implementation.**
Copy the sentence from the issue into your test name. If the issue says "without
causing reader-position jumps", the assertion has to measure reader position —
not "the row got taller". If a test hits behavior you did not expect, decide
whether it is a bug before you pin it as expected.

**3. Anything destructive must converge when re-run after an interruption.**
Validate to the point of actual executability before you mutate. Put the whole
sequence in one transaction. Never use the name of the target state as the
completion marker. The test is: if the process dies on any line, does the next
start heal itself?

**4. Read the neighbouring implementation first, and reuse the concepts that
already exist.**
Adding a provider means reading `claude.ts`, `codex.ts`, and `kimi.ts` in full
first. Needing "don't display this row" means grepping for `visibility` before
inventing a field. The burden of proof for a new concept, field, state, or file
type is on the PR: say why the existing one is insufficient. The ADRs in
`docs/adr/` are constraints, not suggestions.

**5. Treat all transcript content as attacker-controlled.**
It is written by third-party agents. Any path where a transcript value reaches
`shell.*`, `fs.*`, `innerHTML`, or SQL/DDL is deny-by-default.

**6. Re-run verification on the final head.**
Merging main invalidates every claim in your PR description, including your own
"known limitations". Run the suites that cover the line you touched, not only
the test you added.

---

## Renderer / Electron UI changes

Proving the new element renders correctly is one third of the job. You also owe
evidence that it does not disturb virtual scrolling, async timing, existing
interactions, or the full Electron suites.

- Any change that can affect row height — new elements, async media, fonts,
  spacing, the shape of `renderMarkdown` output — needs a **reader-anchor
  assertion**: content above the viewport settling must not move the row the
  user is looking at. Follow the existing pattern in
  `app/tests/electron-session-virtualization.mjs`.
- Cover **three states, not just the final one**: mount, size-available-but-not-
  loaded, and load/error. Progressive images reach their final size long before
  `load` fires; signalling only on `load` will miss it.
- **Idle and mid-scroll are different scenarios.** `virtual-core`'s `resizeItem`
  skips scroll compensation for already-measured rows when
  `scrollDirection === 'backward'`, so drift can be zero at rest and large while
  scrolling up. Test both.
- Run `npm run test:electron:all` (all five suites), not only the suite you
  added.
- **Do not add `loading="lazy"` to virtualized rows.** Rows already mount near
  the viewport; lazy only defers decode into the scroll itself.
- **No hardcoded colors or type sizes inside shadow DOM.** Custom properties
  pierce the shadow boundary — use `var(--muted)`, `var(--hairline-strong)`,
  `var(--text-sm)`.
- **One visual treatment per user-visible concept.** "Blocked source" and "failed
  to load" are the same thing to a reader; they must not render two different
  ways.
- When you depend on a library's calling convention, either accept both shapes or
  pin the assumption in code. A silent signature change that degrades every item
  to a fallback is invisible to types and tests.
- **Every renderer-side probe needs a deadline and an `error` → reject path.** A
  promise with no rejection path plus a bare `await` turns a regression into a
  hung CI job instead of a red one.
- **No assertions with sub-pixel headroom.** Self-calibrate (e.g. take the median
  gap of currently mounted rows as the baseline) instead of hardcoding a
  threshold that a spacing tweak turns red.

## Provider adapters

- **Read `claude.ts`, `codex.ts`, and `kimi.ts` before writing a new adapter.**
  The conventions there are earned: zero-padded ordinals in ids
  (`parsing.ts` uses `padStart(6, '0')`), the
  `__<provider>_canonical_transcript_vN__` marker, how `git_branch` is handled.
- **Session identity must not be the source id alone.** Use a composite such as
  (normalized cwd, header id). Explicit session ids are usually project-local, so
  two projects may legitimately collide — and the second one indexed will
  overwrite the first.
- **A test must actually call `discover()`.** Asserting the resolved root string
  passes even when the directory-layout assumption is wrong.
- **Verify directory layout against the upstream source or format docs**, not
  against what your own machine happens to look like. A tool's default root and
  its custom root often have different nesting.
- **The canonical transcript invariant (ADR-0007) is a hard gate**: assembling
  directly from your adapter must equal assembling after a SQLite round-trip. Any
  design where duplicate ids merge or overwrite breaks it.
- **Never drop a record just because it has no text.** Image-only messages and
  aborted turns that carry usage must still emit a row (`text: null`,
  `content_type: 'unknown'`), or token accounting and the timeline develop holes.
- **Bump `indexVersionMarker` whenever you change uuid format, role
  normalization, or anything else affecting already-stored rows.** Otherwise the
  mtime short-circuit in discovery leaves old-format rows in the database
  forever.
- **Express "this should not be shown" with the existing `visibility` field**
  (`providers/types.ts`), which is defined as provider-normalized display
  eligibility and already has a consumer in the assembler. Do not add a third
  meaning to `is_sidechain`.
- **Cursors must detect same-millisecond rewrites**: mtime + ctime + size + inode,
  not mtime alone. Reconcile moves, copies, deletes, and replacements.
- **Version gates must tolerate the unknown.** Throwing on an unexpected higher
  version makes one bad file trigger a full re-index every run, because the
  provider's index markers are withheld while any unit fails. Skip and record
  instead of poisoning the provider.

## Schema and migrations

- `schema.sql` is pinned by sha256 in `tests/provider-schema-stability.test.mjs`.
  Changing it is an explicit decision plus a full re-index: justify it in the PR
  and update the hash in the same commit. Prefer additive changes.
- **Destructive DDL goes in one transaction.** The repository already has
  `runWriteTransaction` (`packages/core/src/tx.ts`) and both SQLite adapters, and
  the entry points already hold the writer lease — you do not need to invent a
  migration marker.
- **Do not use the name of the target state as the completion marker.** If the
  process is interrupted after CREATE but before the rebuild finishes, comparing
  the current setting against the requested one reports success forever and the
  data is never backfilled.
- **Validate to executability, not to lexical shape.** A regex that accepts a
  string SQLite will reject means you drop the table and then fail.
- **Before writing one value across every table, check whether any table carries
  its own arguments.** Overwriting them leaves the migration looking complete,
  so it never self-heals.
- **Any external input spliced into DDL needs an allowlist and an injection test
  case.**

## Main process and untrusted input

- **Transcript paths must not reach `shell.openPath` unguarded.** On macOS,
  `.app` / `.command` / `.sh` are executed, not opened. Confirmation dialogs must
  default to Cancel.
- **Reading a file because a transcript said so requires an allowlist**, scoped to
  the session's project cwd or known source roots.
- **Do not decode untrusted text through `innerHTML` or a detached `<textarea>`.**
  Decode the specific entities your markdown library actually emits, escape on
  the way out, and pin "decode exactly once" with a test (`&amp;lt;` must stay
  `&lt;`).
- **No synchronous IO in the main process.** A network mount or UNC path freezes
  the whole UI. Use `fs.promises`.
- **Do not broaden interception beyond your feature.** Catching every `file:`
  navigation when you only meant to handle markdown links affects everyone else.
- **Main and preload sources are TypeScript** (ADR-0005). `app/tsconfig.json` sets
  `checkJs: false`, so a `.mjs` module has no type coverage at all.

## Indexing, daemon, and write ownership

- **The heartbeat decides who may write.** While a daemon is fresh, the CLI side
  is read-only: no write connection, no schema migration, no PRAGMA change, no
  checkpoint, no indexing. Guarded by `tests/daemon-arbitration.test.mjs` and
  `tests/app-writer-lease.test.mjs`.
- **If you add something that needs periodic refresh, prove its refresh point is
  actually called repeatedly.** Hanging a full rebuild off a first-run-only gate
  means it runs once and never again — and for existing installations, never at
  all.
- **`daemon_active` must not swallow a configuration change.** Distinguish
  "correctly skipping" from "configuration mismatch"; the latter is an explicit
  error, not a silent fallback to a stale index.
- **State your reasoning when choosing triggers vs. full rebuild.** For example,
  rows written with `INSERT OR REPLACE` do not fire DELETE triggers while
  `recursive_triggers` is off, so a trigger-based refresh would leave stale text
  behind.

---

## Verification contract

Every PR:

1. `npm test`, `npm run typecheck` (root and app tsconfig), `npm run lint` — all
   green. Quote the **numbers** in the PR description.
2. Touching `app/` also requires `npm run test:electron:all`.
3. **After merging main, re-run everything.** Conclusions from before the merge —
   including any "known limitation" you documented — are void.
4. **Do not loosen an existing assertion.** If one must change, give it its own
   section in the PR description explaining why the original was wrong.
5. **Fixtures are real provider output**, not hand-written approximations.
6. **Confirm your new tests actually run in CI** (`.github/workflows/`).

## Scope and review

- One PR does one thing. Note explicitly anything you deliberately left out.
- If you are unsure about a design decision, say so in the PR instead of
  guessing — an open question is cheaper to resolve than a silent assumption.
- Do not ship a code path you have flagged to yourself as unverified. Writing
  "this call site is worth another look" is honest, but it belongs in a follow-up
  issue, not in the diff.